New candidate JEP: 467: Markdown Documentation Comments

[Mark Rotteveel]

On 27/02/2024 21:31, Mark Reinhold wrote:
> https://openjdk.org/jeps/467
> 
>    Summary: Enable JavaDoc documentation comments to be written in
>    Markdown rather than solely in a mixture of HTML and JavaDoc @-tags.

The JEP mentions @implSpec as if it is a standard tag, but @implSpec is 
not a standard Javadoc tag, it is a custom tag defined for the JDK 
build. It is not available in standard Javadoc.

I mean, in the context of the example it is acceptable it is mentioned, 
but I think it needs to be made clear that it is a non-standard tag. For 
example, to avoid problems like in Effective Java third edition, which 
also assumed it was a standard tag and used it, in item 19.

As an aside, maybe it should be considered making @implSpec and 
@implNote standard tags in some other JEP.

Mark
-- 
Mark Rotteveel