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.w...@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.w...@oracle.com >>>> <mailto:huizhe.w...@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.w...@oracle.com >>>>>> <mailto:huizhe.w...@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>La >>>>>> nce.ander...@oracle.com >>>>>> <mailto:lance.ander...@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>La >>>> nce.ander...@oracle.com >>>> <mailto:lance.ander...@oracle.com> >>>> >>>> >>>> >>>> >>>> >>> >
