
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