RFR: JDK-8262875: doccheck: empty paragraphs, etc in java.base module

Tue Mar 2 20:34:37 UTC 2021

Bernd,

With respect, I disagree.

There is a difference between `<body>text</body>` and 
`<body><p>text</p></body>`.

Anyway, the significant comment in this context is that it is being used 
as a terminator, at the logical end of the paragraph.

doccheck is using the standard `htmltidy` command to detect issues in 
HTML, and it is that program that is reporting the empty paragraphs.

As for the guide that you reference, it is very, very old. I note that 
it begins:

>
>       Introduction
>
> *Principles*
>
> At Java Software, we have several guidelines
>

i.e. note the "Java Software" ...

-- Jon

   On 3/2/21 12:04 PM, Bernd Eckenfels wrote:
> Hello,
>
> Actually, in HTML <p> was a separator, and in xhtml it should enclose paragraphs. However I was under the impression Javadoc always used the separator style (it would be strange to start the first sentence in Javadoc with <p>. Is this doccheck enforcing a new policy?
>
> This officially Oracle guide for example has a different example:
>
> https://www.oracle.com/de/technical-resources/articles/java/javadoc-tool.html#format
>
> Gruss
> Bernd
>
>
> --
> http://bernd.eckenfels.net
> ________________________________
> Von: net-dev <net-dev-retn at openjdk.java.net> im Auftrag von Jonathan Gibbons <jjg at openjdk.java.net>
> Gesendet: Tuesday, March 2, 2021 8:41:03 PM
> An: core-libs-dev at openjdk.java.net <core-libs-dev at openjdk.java.net>; hotspot-compiler-dev at openjdk.java.net <hotspot-compiler-dev at openjdk.java.net>; net-dev at openjdk.java.net <net-dev at openjdk.java.net>; security-dev at openjdk.java.net <security-dev at openjdk.java.net>
> Betreff: RFR: JDK-8262875: doccheck: empty paragraphs, etc in java.base module
>
> Please review some minor doc fixes, for issues found by _doccheck_.    There are two kinds of errors that are addressed.
>
> 1. Incorrect use of `<p>`. In HTML, `<p>` marks the *beginning* of a paragraph. It is not a terminator, to mark the end of a paragraph, or a separator to mark the boundary between paragraphs.  In particular, it should not be used at the end of a description before a javadoc block tag, such as `@param` or before other HTML block tags, like `<ul>` or `<table>`.
>
> 2. References to the id `package-description`, following the recent standardization of all ids generated by javadoc,
>
> -------------
>
> Commit messages:
>   - JDK-8262875: doccheck: empty paragraphs, etc in java.base module
>
> Changes: https://git.openjdk.java.net/jdk/pull/2795/files
>   Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=2795&range=00
>    Issue: https://bugs.openjdk.java.net/browse/JDK-8262875
>    Stats: 9 lines in 8 files changed: 0 ins; 1 del; 8 mod
>    Patch: https://git.openjdk.java.net/jdk/pull/2795.diff
>    Fetch: git fetch https://git.openjdk.java.net/jdk pull/2795/head:pull/2795
>
> PR: https://git.openjdk.java.net/jdk/pull/2795