Permite que os comentários da documentação do JavaDoc sejam escritos em Markdown, em vez de apenas em uma mistura de HTML e JavaDoc @-tags.
JEP 467, Markdown Documentation Comments, foi promovido para ser liberado no JDK 23
Objetivos da JEP
Tornar os comentários da documentação da API mais fáceis de escrever e ler no formato de origem, introduzindo a capacidade de usar a sintaxe Markdown nos comentários da documentação, juntamente com elementos HTML e tags JavaDoc.
Estende a API Compiler Tree para permitir que outras ferramentas que analisam comentários de documentação manipulem o conteúdo Markdown nesses comentários.
Não é o objetivo desta JEP, permitir a conversão automatizada de comentários de documentação existentes para a sintaxe Markdown.
Motivação
Os comentários da documentação Java tradicionalmente usam tags HTML e JavaDoc, uma escolha prática em 1995, mas desde então se tornou menos conveniente. HTML é prolixo e difícil de escrever à mão, especialmente para desenvolvedores que talvez não estejam familiarizados com ele. Tags JavaDoc embutidas, como {@link} e {@code}, são complicadas e muitas vezes exigem documentação de referência para uso adequado.
Markdown, por outro lado, é uma linguagem de marcação leve e fácil de ler e escrever. Ele oferece suporte a estruturas de documentos simples, como parágrafos, listas, texto estilizado e links, tornando-o um substituto adequado para HTML em comentários de documentação. Além disso, o Markdown permite a inclusão de HTML para construções que não suportam diretamente, proporcionando flexibilidade e reduzindo a complexidade.
Como exemplo do uso de Markdown em um comentário de documentação, considere o comentário para java.lang.Object.hashCode:
/**
* Returns a hash code value for the object. This method is
* supported for the benefit of hash tables such as those provided by
* {@link java.util.HashMap}.
* <p>
* The general contract of {@code hashCode} is:
* <ul>
* <li>Whenever it is invoked on the same object more than once during
* an execution of a Java application, the {@code hashCode} method
* must consistently return the same integer, provided no information
* used in {@code equals} comparisons on the object is modified.
* This integer need not remain consistent from one execution of an
* application to another execution of the same application.
* <li>If two objects are equal according to the {@link
* #equals(Object) equals} method, then calling the {@code
* hashCode} method on each of the two objects must produce the
* same integer result.
* <li>It is <em>not</em> required that if two objects are unequal
* according to the {@link #equals(Object) equals} method, then
* calling the {@code hashCode} method on each of the two objects
* must produce distinct integer results. However, the programmer
* should be aware that producing distinct integer results for
* unequal objects may improve the performance of hash tables.
* </ul>
*
* @implSpec
* As far as is reasonably practical, the {@code hashCode} method defined
* by class {@code Object} returns distinct integers for distinct objects.
*
* @return a hash code value for this object.
* @see java.lang.Object#equals(java.lang.Object)
* @see java.lang.System#identityHashCode
*/ |
Este comentário pode ser escrito em Markdown da seguinte forma:
/// Returns a hash code value for the object. This method is
/// supported for the benefit of hash tables such as those provided by
/// [java.util.HashMap].
///
/// The general contract of `hashCode` is:
///
/// - Whenever it is invoked on the same object more than once during
/// an execution of a Java application, the `hashCode` method
/// must consistently return the same integer, provided no information
/// used in `equals` comparisons on the object is modified.
/// This integer need not remain consistent from one execution of an
/// application to another execution of the same application.
/// - If two objects are equal according to the
/// [equals][#equals(Object)] method, then calling the
/// `hashCode` method on each of the two objects must produce the
/// same integer result.
/// - It is _not_ required that if two objects are unequal
/// according to the [equals][#equals(Object)] method, then
/// calling the `hashCode` method on each of the two objects
/// must produce distinct integer results. However, the programmer
/// should be aware that producing distinct integer results for
/// unequal objects may improve the performance of hash tables.
///
/// @implSpec
/// As far as is reasonably practical, the `hashCode` method defined
/// by class `Object` returns distinct integers for distinct objects.
///
/// @return a hash code value for this object.
/// @see java.lang.Object#equals(java.lang.Object)
/// @see java.lang.System#identityHashCode |
Principais diferenças a serem observadas:
O uso de Markdown é indicado por uma nova forma de comentário de documentação em que cada linha começa com /// em vez da sintaxe tradicional /** ... */.
O elemento HTML <p> não é obrigatório; uma linha em branco indica uma quebra de parágrafo.
Os elementos HTML <ul> e <li> são substituídos por marcadores de lista com marcadores Markdown, usando - para indicar o início de cada item na lista.
O elemento HTML <em> é substituído por sublinhados (_) para indicar a alteração da fonte.
As instâncias da tag {@code ...} são substituídas por crases (`...`) para indicar a fonte monoespaçada.
Instâncias de {@link ...} para vincular a outros elementos do programa são substituídas por formas estendidas de links de referência Markdown.
Instâncias de tags de bloco, como @implSpec, @return e @see, geralmente não são afetadas, exceto que o conteúdo dessas tags agora também está em Markdown, por exemplo, aqui nos crases do conteúdo da tag @implSpec.
A imagem abaixo compara as duas versões:
Referências:
https://www.infoq.com/news/2024/05/jep467-markdown-in-javadoc/
https://openjdk.org/jeps/467
Comentários
Postar um comentário