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

-Joe

...

otherwise it is OK

Best Lance On Jun 11, 2014, at 11:54 AM, huizhe wang <huizhe.wang@oracle.com> wrote:

...

Fix some typos in the JAXP documentation. Please review.

http://cr.openjdk.java.net/~joehw/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 Lance.Andersen@oracle.com

Lance Andersen| Principal Member of Technical Staff | +1.781.442.2037 Oracle Java Engineering 1 Network Drive Burlington, MA 01803 Lance.Andersen@oracle.com

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

-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@oracle.com <mailto:huizhe.wang@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.htm...

-Joe

...

otherwise it is OK

Best Lance On Jun 11, 2014, at 11:54 AM, huizhe wang <huizhe.wang@oracle.com <mailto:huizhe.wang@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@oracle.com <mailto:Lance.Andersen@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@oracle.com <mailto:Lance.Andersen@oracle.com>

Hi, It is easier to read and maintain the source code if there is less clutter and markup. Previous consensus seemed to be to omit closing html when not required. Roger On 6/17/2014 12:33 AM, huizhe wang 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-inc...

-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@oracle.com <mailto:huizhe.wang@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.htm...

-Joe

...

otherwise it is OK

Best Lance On Jun 11, 2014, at 11:54 AM, huizhe wang <huizhe.wang@oracle.com <mailto:huizhe.wang@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@oracle.com

<mailto:Lance.Andersen@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@oracle.com

<mailto:Lance.Andersen@oracle.com>

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

Cheers, Paul

On Mon, Jun 16, 2014 at 11:33 PM, huizhe wang <huizhe.wang@oracle.com <mailto:huizhe.wang@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-inc...

-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@oracle.com <mailto:huizhe.wang@oracle.com> <mailto:huizhe.wang@oracle.com <mailto:huizhe.wang@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.htm...

-Joe

otherwise it is OK

Best Lance On Jun 11, 2014, at 11:54 AM, huizhe wang <huizhe.wang@oracle.com <mailto:huizhe.wang@oracle.com> <mailto:huizhe.wang@oracle.com <mailto:huizhe.wang@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@oracle.com <mailto:Lance.Andersen@oracle.com> <mailto:Lance.Andersen@oracle.com <mailto:Lance.Andersen@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@oracle.com <mailto:Lance.Andersen@oracle.com> <mailto:Lance.Andersen@oracle.com <mailto:Lance.Andersen@oracle.com>>

Thanks Stuart for the good discussion. It reminds us that optional tags may be not optional since we're writing Doc Comments that will become part of the spec and affect overall look of it. The issues you pointed out below may be true generally when writing <p> tag in a html file. However, we're talking about the JavaDoc here. The Doc Comments consist of two parts: a description followed by block tags. The JavaDoc tool will put the description in a <div> block, so no content will be outside of the block. (the block tags will be in Description List <dl> by the way). In Doc Comments, a <p> tag serves only to separate paragraphs. As for clutter, you probably hate xml then :-) I consider html tags are generally short and tidy. But again, it's preference, if no </p> is the norm, I'll do the same. -Joe On 6/17/2014 3:38 PM, Stuart Marks wrote:

On 6/16/14 9:33 PM, huizhe wang wrote:

...

It's not xhmtl, but I would think closing tags is a good practice. Being explicit is always a good thing to do.

Being explicit sounds good, but in this case it leads to errors; see below.

...

...

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.

If content slips outside of a <p> element, it's indeed an error. (*1) But it's almost impossible for this to happen if you omit the </p> end tag. If one doesn't use </p> end tags, the <p> element can only be implicitly closed by a) closing its enclosing element, e.g., <div>; or b) by starting a new block-level element such as a <div>, <h1>, etc., or another <p> element. With this approach the text is always (*2) going to be within some block-level element.

By contrast, if one were to use </p> end tags, there is the possibility between every paragraph for text to appear, which means that it would be outside of any paragraph element. The use of </p> end tags creates this possibility, and thus this increases the possibility of error.

*1 - not an error in the sense of being a syntax error, or one that javadoc would warn or raise an error about, but a semantic error in that text would occur in an inappropriate place in the document structure.

*2 - well, not always. It's possible for text to be outside of any block element at the very beginning of the element, such as after <body> but before the first <p> or other block-level element.

...

...

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.

I'm not sure what the author's intent was, but it looks like a mistake to me. The problem is that <code> is an inline element and can appear within a <p> or other block element. Unlike block elements, an inline element doesn't implicitly close a <p> element. The author might have thought that <code> itself was a block element and thus didn't need to be enclosed by a block element, but this isn't the case.

What's probably necessary here is for the text within <code> to be enclosed within a block element, such as <p>, <blockquote>, or <pre>.

...

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

It does, but it's possible for the style sheet to have styles for descendant (enclosed) elements, or for styles to inherit properties from enclosing elements. For example, a style sheet might have these declarations:

p code { blag bleg blig; } pre code { bazz bizz buzz; }

This would style <code> text differently within <p> elements from <code> text within <pre> elements. But these declarations would miss the <code> text from QName.java, because it doesn't occur within these elements.

* * *

Now, this really is moot, since the offending example is on a private field that will almost never get rendered, the stylesheet doesn't in fact use that style of CSS selector, and the prevailing style of the javadoc in this area is to use </p> end tags. It's probably not worth it to go in and remove all the end tags, and it's certainly not worth it if we're taking code from upstream somewhere that is already marked-up this way. So don't consider this to be a proposal or an exhortation to clean out all the </p> end tags.

But if you're writing new javadoc, I recommend that you not use </p> end tags.

(Also, as Roger pointed out, they add clutter.)

s'marks

...

...

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

-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@oracle.com <mailto:huizhe.wang@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.htm...

-Joe

> > otherwise it is OK > > Best > Lance > On Jun 11, 2014, at 11:54 AM, huizhe wang <huizhe.wang@oracle.com > <mailto:huizhe.wang@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@oracle.com > > > <mailto:Lance.Andersen@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@oracle.com

<mailto:Lance.Andersen@oracle.com>