commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Emmanuel Bourg <ebo...@apache.org>
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:
  <ul>
    <li>One</li>
    <li>Two</li>
    <li>Three</li>
  </ul>
  Have a nice day!</p>

and:

  <p>TOTO list:</p>
  <ul>
    <li>One</li>
    <li>Two</li>
    <li>Three</li>
  </ul>
  <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: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org


Mime
View raw message