JEP 467: Comentários de documentação em Markdown

Objetivo

Oferecer suporte à sintaxe Markdown nos comentários de documentação do Java para melhorar a legibilidade e incentivar uma documentação mais concisa.

Motivação

• O JavaDoc tradicional depende de tags HTML → é verboso demais e difícil de ler.
• Os desenvolvedores já estão acostumados com Markdown em README, GitHub etc.
• Com suporte a Markdown, é possível escrever documentação de forma consistente e concisa.

Descrição

• Suporte à sintaxe Markdown baseada em CommonMark dentro dos comentários do JavaDoc.
• Os comentários HTML existentes continuam podendo ser usados.
• Em vez do estilo de comentário existente /* ... */, usa-se /// para indicar que se trata de um comentário de documentação em Markdown.
• Ferramentas JavaDoc de terceiros fazem o parsing e a renderização do Markdown.

Especificação do Markdown

• Baseado em CommonMark.
• Sintaxe suportada:
  • Títulos (#, ##, ### etc.)
  • Listas (ordenadas/não ordenadas)
  • Blocos de código (```)
  • Links
  • Tabelas (no formato Github Flavored Markdown)
  • Citações
  • Ênfase (*itálico*, **negrito**)

Tags específicas do Java

Com o Markdown, ainda é possível usar as tags @ do JavaDoc existentes:

• @param
• @return
• @throws
• @see
• @since
• @deprecated

[devnamho0910]

Excelente...

[carnoxen]

Parece que foi incorporado ao padrão.

[click]

Foi incluído no JDK 23.
Nos meus testes, mesmo que a versão do JDK do projeto seja inferior à 23, funciona normalmente se a IDE ou a ferramenta de exportação do Javadoc oferecer suporte.