Mailing-List: contact dev-help@commons.apache.org; run by ezmlm
Precedence: bulk
Reply-To: "Commons Developers List" <dev@commons.apache.org>
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8;
 format=flowed
Content-Transfer-Encoding: 8bit
Date: Thu, 29 Sep 2016 01:37:37 +0200
From: Gilles <gilles@harfang.homelinux.org>
To: <dev@commons.apache.org>
Subject: [RNG] How to write Javadoc (Was: ... commit: Fixed the javadoc
 errors with Java 8)
In-Reply-To: <15f03076-3dde-423b-d0eb-e83bec3113b2@apache.org>
References: <cacdbd5db7de4c58bded7a6db68feb0b@git.apache.org>
 <5cfd91175be15ecaecdf838151c4bc0c@scarlet.be>
 <4777913a-a93e-1091-1afd-a7df3c7f7d13@apache.org>
 <b6b067997680d790d282e1e0acdc32f3@scarlet.be>
 <15f03076-3dde-423b-d0eb-e83bec3113b2@apache.org>
Message-ID: <affea5cca3a610e243498902f4e80f57@scarlet.be>
User-Agent: Scarlet Webmail
X-DCC-scarlet.be-Metrics: eir; whitelist
X-Virus-Scanned: clamav-milter 0.98.1-exp at eir
X-Virus-Status: Clean
archived-at: Wed, 28 Sep 2016 23:37:55 -0000


Thanks for the non-trivial details that make the change
understandable.

It would have been nice to post this information on the ML,
before applying the changes.
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".

With this new specification (where laziness is not forgiven),
it is even more important than it was (when I raised the
issue, and nobody gave a damn) to decide together how to
layout Javadoc comments (so that they are both readable in
code and compliant).

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, and makes the Javadoc
difficult to read.

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


Gilles


On Thu, 29 Sep 2016 00:59:48 +0200, Emmanuel Bourg wrote:
> Le 28/09/2016 à 16:40, Gilles a écrit :
>
>> They are not trivial issues, because they are not seen by everyone.
>
> I'm not sure I have the same definition of "trivial" in my dictionary 
> :)
>
>
>> Below, you refer to HTML 5.
>>
>> Is the "javadoc" tool assuming that its input is valid HTML 5?
>
> Javadoc in Java 8 is HTML 4 compliant, it'll switch to HTML 5 in Java 
> 9
> (see JEP 224 [1]).
>
> But the rule I mentioned isn't new in HTML 5, it existed before:
>
> https://www.w3.org/TR/html401/struct/text.html#edef-P
>
> "The P element represents a paragraph. It cannot contain block-level
> elements (including P itself)."
>
>
>> Several years ago, I raise the issue of writing "valid" HTML/XHTML.
>>
>> At the time, the answer had been that the Javadoc specification
>> referred to an older HTML version, and that it was not going to
>> change, and thus not worth updating the docs in any consistent
>> way with the recommendation of W3C.
>>
>> Has that changed?
>
> It changed with Java 8 enforcing the correctness of the HTML output.
>
>
>> No, I purposefully removed that option before rerunning "mvn clean 
>> site"!
>
>> Perhaps you've run into
>>   https://issues.apache.org/jira/browse/RNG-1
>>
>> All I'm saying is that change must be clarified because it is 
>> definitely
>> not "Java 8" as such that causes the trouble.
>
> Are you using OpenJDK 8 on Debian/Ubuntu? doclint is disabled by 
> default
> on these systems [2].
>
> Emmanuel Bourg
>
> [1] http://openjdk.java.net/jeps/224
> [2]
> 
> https://sources.debian.net/src/openjdk-8/8u102-b14.1-2/debian/patches/disable-doclint-by-default.diff/
>
>


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org