commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Emmanuel Bourg <>
Subject Re: [RNG] How to write Javadoc (Was: ... commit: Fixed the javadoc errors with Java 8)
Date Thu, 29 Sep 2016 08:55:07 GMT
Le 29/09/2016 à 01:37, Gilles a écrit :

> The more so that the issue was encountered by several people
> in different components, and IIRC now, the consensus (or
> workaround) had been to indeed disable "doclint".

This is a wise workaround, fixing old Javadocs is a waste of time, but
it isn't forbidden. If RNG had hundred of HTML errors I would have just
disabled doclint when "mvn javadoc:javadoc" is used, but here it was
easy to fix.

> when I raised the issue, and nobody gave a damn

Probably because Javadoc formatting issues aren't important enough for
people to bother.

> I've used <p></p> to create a _paragraph_:
>  "a distinct section of a piece of writing, usually dealing
>   with a single theme and indicated by a new line, indentation,
>   or numbering"
> Your usage of <p>, even if compliant with the HTML spec, does
> not comply with the above definition

Maybe you should bring your concerns to the HTML Working Group then.

> and makes the Javadoc difficult to read.

The modification I made has no visual impact. These two snippets:

  <p>TOTO list:
  Have a nice day!</p>


  <p>TOTO list:</p>
  <p>Have a nice day!</p>

are rendered identically in modern browsers. And the code readability
isn't that different.

> Is there an HTML element which we can use to make a paragraph
> (that would allow sample code or a list within it)?

You can use a <div> to mix inline text and lists, but you lose the
paragraph semantic and the top/bottom margins.

Emmanuel Bourg

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message