New candidate JEP: 467: Markdown Documentation Comments

Mark Rotteveel mark at lawinegevaar.nl
Wed Feb 28 08:55:00 UTC 2024


On 28/02/2024 09:48, Mark Rotteveel wrote:
> 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.

Maybe I should learn to read to full JEP before commenting. Later in the 
document it is mentioned they are custom tags, but maybe the first use 
of @implSpec needs to make clear it is a custom tag as well.

Mark
-- 
Mark Rotteveel



More information about the jdk-dev mailing list