RFR: 8046443 : A few typos in JAXP JavaDoc
Stuart Marks
stuart.marks at oracle.com
Tue Jun 17 17:08:45 UTC 2014
Hi Paul,
That thread, while interesting -- maybe :-) -- is about a somewhat different
issue: self-closing tags as opposed to optional end tags. Self-closing tags were
never part of HTML4 and thus are strictly illegal. In practice many people use
them and many browsers accept them, leading to a discussion about whether
javadoc should issue warnings or errors when encountering them.
There's no question about the legality of using or omitting end tags in the case
where they're specified to be optional, as in the case of the <p> element. The
question is about whether using them is or isn't good practice.
s'marks
On 6/17/14 6:31 AM, Paul Benedict wrote:
> This thread is a good reference on JDK 8's lint enforcement of HTML in
> javadoc. You can see the reasons behind not allowing self-enclosing tags and
> enforcing HTML:
> http://mail.openjdk.java.net/pipermail/core-libs-dev/2013-July/thread.html#19269
>
>
> Cheers,
> Paul
>
>
> On Mon, Jun 16, 2014 at 11:33 PM, huizhe wang <huizhe.wang at oracle.com
> <mailto:huizhe.wang at oracle.com>> wrote:
>
>
> 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>
> <mailto: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>
> <mailto: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/>
> <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>
> <mailto: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>
> <mailto:Lance.Andersen at oracle.com
> <mailto:Lance.Andersen at oracle.com>>
>
>
>
>
>
>
>
More information about the core-libs-dev
mailing list