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