RFR: 8046443 : A few typos in JAXP JavaDoc

Tue Jun 17 04:33:25 UTC 2014

On 6/16/2014 5:35 PM, Stuart Marks wrote:
> 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).

It's not xhmtl, but I would think closing tags is a good practice. Being 
explicit is always a good thing to do. It also provides a nice structure 
(NetBeans would auto-close it with an indentation), e.g.:
<p>
        this is paragraph 1
</p>

although, the JAXP javadoc wasn't written with any good structure.

>
> 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.

That seems to be an argument for a closing tag. When a style is 
specified for <p>, closing tag makes it clear where exactly it would be 
applied -- it's content inside paragraphs, not the whole <body>. If 
there's anything "slipped" outside of the P tags, it would be an error.

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

In this example, I think it was intentional by the author to add the 
closing tag to separate the paragraphs, otherwise he would have to add 
another <p> before <code>.

>
>      * <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.

with css, <code> would have its own style.

>
> 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.

haha, <pedantry> can be put to good use in our writings :-)

-Joe

>
>
>
>
> 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>
>>>
>>>
>>>
>>>
>>