writing JavaDoc- Re: RFR: 8046443 : A few typos in JAXP JavaDoc

2014-06-18 Thread huizhe wang
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,

Re: RFR: 8046443 : A few typos in JAXP JavaDoc

2014-06-17 Thread roger riggs
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,

Re: RFR: 8046443 : A few typos in JAXP JavaDoc

2014-06-17 Thread Paul Benedict
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,

Re: RFR: 8046443 : A few typos in JAXP JavaDoc

2014-06-17 Thread Stuart Marks
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

Re: RFR: 8046443 : A few typos in JAXP JavaDoc

2014-06-17 Thread Stuart Marks
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

Re: RFR: 8046443 : A few typos in JAXP JavaDoc

2014-06-16 Thread Stuart Marks
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

Re: RFR: 8046443 : A few typos in JAXP JavaDoc

2014-06-16 Thread huizhe wang
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

RFR: 8046443 : A few typos in JAXP JavaDoc

2014-06-11 Thread huizhe wang
Fix some typos in the JAXP documentation. Please review. http://cr.openjdk.java.net/~joehw/jdk9/8046443/webrev/ Thanks, Joe

Re: RFR: 8046443 : A few typos in JAXP JavaDoc

2014-06-11 Thread Chris Hegarty
Looks good to me Joe. -Chris. On 11/06/14 16:54, huizhe wang wrote: Fix some typos in the JAXP documentation. Please review. http://cr.openjdk.java.net/~joehw/jdk9/8046443/webrev/ Thanks, Joe

Re: RFR: 8046443 : A few typos in JAXP JavaDoc

2014-06-11 Thread Daniel Fuchs
Hi Joe, Looks good! -- daniel On 6/11/14 5:54 PM, huizhe wang wrote: Fix some typos in the JAXP documentation. Please review. http://cr.openjdk.java.net/~joehw/jdk9/8046443/webrev/ Thanks, Joe

Re: RFR: 8046443 : A few typos in JAXP JavaDoc

2014-06-11 Thread huizhe wang
Thanks Daniel, Chris! -Joe On 6/11/2014 9:11 AM, Daniel Fuchs wrote: Hi Joe, Looks good! -- daniel On 6/11/14 5:54 PM, huizhe wang wrote: Fix some typos in the JAXP documentation. Please review. http://cr.openjdk.java.net/~joehw/jdk9/8046443/webrev/ Thanks, Joe

Re: RFR: 8046443 : A few typos in JAXP JavaDoc

2014-06-11 Thread Lance Andersen
Hi Joe, please change dont to don't I would get rid of the p/p otherwise it is OK Best Lance On Jun 11, 2014, at 11:54 AM, huizhe wang huizhe.w...@oracle.com wrote: Fix some typos in the JAXP documentation. Please review. http://cr.openjdk.java.net/~joehw/jdk9/8046443/webrev/

Re: RFR: 8046443 : A few typos in JAXP JavaDoc

2014-06-11 Thread huizhe wang
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

Re: RFR: 8046443 : A few typos in JAXP JavaDoc

2014-06-11 Thread Lance Andersen
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 pblah/p blocks was needed and just use p Best Lance On Jun 11, 2014, at 1:20 PM, huizhe wang huizhe.w...@oracle.com wrote: On 6/11/2014 9:48 AM, Lance

Re: RFR: 8046443 : A few typos in JAXP JavaDoc

2014-06-11 Thread huizhe wang
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,