RFR: 8046443 : A few typos in JAXP JavaDoc

[Stuart Marks]

This is somewhat moot at this point, but....

I'd recommend against using paragraph end tags </p>. Paragraph end tags really 
are optional in HTML. I've heard some advocates of end tags, such as commenters 
on the linked web page, say that end tags are somehow "more correct" (wrong) or 
that end tags should be used "because XHTML" (javadoc is HTML4, not XHTML).

The problem with using the </p> end tag is that it's easy for additional textual 
content to slip in afterward. This text would end up as part of the parent 
element. This might result in its being styled incorrectly or otherwise treated 
inconsistently with the rest of the text.

For example, I happened to notice the following in one of the files in the 
patch, jaxp/src/javax/xml/namespace/QName.java:

      * <p>To workaround this issue, serialVersionUID is set with either
      * a default value or a compatibility value.  To use the
      * compatibility value, set the system property:</p>
      *
      * <code>com.sun.xml.namespace.QName.useCompatibleSerialVersionUID=1.0</code>
      *
      * <p>This workaround was inspired by classes in the javax.management
      * package, e.g. ObjectName, etc.

Note that the text enclosed in the <code> element is outside of any paragraph. 
If the style sheet were to have a distinct style for code appearing within a 
paragraph, that style wouldn't apply to the text in this example.

It turns out that this text is from a private field in the QName class 
(serialVersionUID) so it's usually not rendered anyway, but I'd guess that there 
are other places where text has accidentally ended up outside of paragraph 
elements because a paragraph end tag was used and a paragraph start tag (or 
block start tag) was missing.

</pedantry>

s'marks

P.S. Note that the start tag for the <pedantry> element is optional and is 
implied by context.




On 6/11/14 10:49 AM, huizhe wang wrote:
> And, here is a good discussion on closing tags:
>
> http://webdesign.about.com/od/htmltags/qt/optional-html-end-tags-when-to-include-them.htm
>
>
> -Joe
>
> On 6/11/2014 10:24 AM, Lance Andersen wrote:
>> Hi Joe,
>>
>> </p>  is what I am talking about.
>>
>> On the myriad of clean-ups that were needed to be done in JDBC, getting rid of
>> these type of <p>blah</p> blocks was needed and just use <p>
>>
>> Best
>> Lance
>> On Jun 11, 2014, at 1:20 PM, huizhe wang <huizhe.wang at oracle.com
>> <mailto:huizhe.wang at oracle.com>> wrote:
>>
>>>
>>> On 6/11/2014 9:48 AM, Lance Andersen wrote:
>>>> Hi Joe,
>>>>
>>>> please change
>>>>
>>>> dont
>>>>
>>>> to
>>>>
>>>>  don't
>>>
>>> Oops, I committed too quickly.  But this is a dev comment, so we can fix that
>>> in the next patch.
>>>
>>>>
>>>> I would get rid of the <p></p>
>>>
>>> Guide[1] for JavaDoc Tool suggests using <p> to separate paragraphs:
>>> If you have more than one paragraph in the doc comment, separate the
>>> paragraphs with a |<p>|paragraph tag, as shown.
>>>
>>> [1]
>>> http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html
>>>
>>> -Joe
>>>
>>>>
>>>> otherwise it is OK
>>>>
>>>> Best
>>>> Lance
>>>> On Jun 11, 2014, at 11:54 AM, huizhe wang <huizhe.wang at oracle.com
>>>> <mailto:huizhe.wang at oracle.com>> wrote:
>>>>
>>>>> Fix some typos in the JAXP documentation.  Please review.
>>>>>
>>>>> http://cr.openjdk.java.net/~joehw/jdk9/8046443/webrev/
>>>>> <http://cr.openjdk.java.net/%7Ejoehw/jdk9/8046443/webrev/>
>>>>>
>>>>> Thanks,
>>>>> Joe
>>>>>
>>>>>
>>>>>
>>>>
>>>>
>>>> <Mail Attachment.gif>
>>>>
>>>> Lance Andersen| Principal Member of Technical Staff | +1.781.442.2037
>>>> Oracle Java Engineering
>>>> 1 Network Drive
>>>> Burlington, MA 01803
>>>> <http://oracle.com/us/design/oracle-email-sig-198324.gif>Lance.Andersen at oracle.com
>>>> <mailto:Lance.Andersen at oracle.com>
>>>>
>>>>
>>>>
>>>>
>>>
>>
>>
>>
>> Lance Andersen| Principal Member of Technical Staff | +1.781.442.2037
>> Oracle Java Engineering
>> 1 Network Drive
>> Burlington, MA 01803
>> <http://oracle.com/us/design/oracle-email-sig-198324.gif>Lance.Andersen at oracle.com
>> <mailto:Lance.Andersen at oracle.com>
>>
>>
>>
>>
>