Eu tenho um pequeno exemplo de código que quero incluir no comentário do Javadoc para um método.
/**
* -- ex: looping through List of Map objects --
* <code>
* for (int i = 0; i < list.size(); i++) {
* Map map = (Map)list.get(i);
* System.out.println(map.get("wordID"));
* System.out.println(map.get("word"));
* }
* </code>
*
* @param query - select statement
* @return List of Map objects
*/
O problema é que o exemplo de código aparece no Javadoc sem quebras de linha, dificultando a leitura.
-- ex: looping through List of Map objects -- for (int i = 0; i list.size(); i++) { Map map = (Map)list.get(i); System.out.println(map.get("wordID")); System.out.println(map.get("word")); }
Parameters
query - - select statement
Returns:
List of Map objects
Acho que estou errado ao supor que a tag de código lidaria com quebras de linha. Qual é a melhor maneira de formatar exemplos de código nos comentários do Javadoc?
Eu tive um tempo muito difícil ao incluir um exemplo de código específico em um comentário do javadoc. Eu gostaria de compartilhar este.
Por favor observe o seguinte:
<code>
tags para impedir que os colchetes sejam interpretados{@code ...}
tag para incluir os genéricos na saída@Override
via "{@literal @}Override
" porque o gerador javadoc "inclina" lá devido ao fato de o @ ir diretamente após um colchete de abertura{@code
e{@literal
, para compensar os espaços internos e manter o alinhamentocódigo javadoc:
é impresso como
fonte
A fonte java tem muitos bons exemplos para isso. Aqui está um exemplo do cabeçalho de "String.java":
fonte
<pre><blockquote>...</blockquote></pre>
<p><blockquote><pre>
</pre></blockquote></p>
List<String>
. Para isso eu estou usando<pre>{@code ... }</pre>
.Coloque seu código multilinha com
<pre></pre>
tags.fonte
Você precisa das
<pre></pre>
tags para as quebras de linha e de{@code ... }
dentro delas para genéricos. Mas não é permitido colocar a chave de abertura na mesma linha que a<generic>
tag, pois tudo será exibido em uma linha novamente.Exibe em uma linha:
Exibe com quebras de linha:
Outra coisa estranha é que quando você cola a chave de fechamento
{@code
, ela é exibida:Resultado:
fonte
...
``). Você não precisa<code>
e<pre>
tags. Eu editei sua resposta nessa mente.<pre/>
é necessário para preservar as linhas.{@code
deve ter sua própria linha<blockquote/>
é apenas para indentação.ATUALIZAÇÃO com JDK8
Os requisitos mínimos para códigos adequados são
<pre/>
e{@code}
.rendimentos
E um ambiente opcional
<blockquote/>
insere um recuo.rendimentos
Inserir
<p>
ou circundar<p>
e</p>
emitir avisos.fonte
Consegui gerar arquivos HTML de boa aparência com o seguinte snip-it mostrado no Código 1.
(Código 1)
O código 1 se transformou na página HTML javadoc gerada na Figura 1, conforme o esperado.
(Figura 1)
No entanto, no NetBeans 7.2, se você pressionar Alt + Shift + F (para reformatar o arquivo atual), o Código 1 será convertido no Código 2.
(Código 2)
onde o primeiro
<pre>
agora está dividido em duas linhas. O código 2 produz o arquivo HTML javadoc gerado, como mostra a Figura 2.(Figura 2)
A sugestão de Steve B (Código 3) parece dar os melhores resultados e permanece formatada conforme o esperado, mesmo depois de pressionar Alt + Shift + F.
(Código 3)
O uso do Código 3 produz a mesma saída HTML javadoc, como mostrado na Fig 1.
fonte
Aqui estão meus dois centavos.
Como as outras respostas já afirmam, você deve usar
<pre>
</pre>
em conjunto com{@code
}
.Use
pre
e{@code}
<pre>
e</pre>
impedir que ele caia em uma linha;{@code
}
impede<
,>
e tudo no meio de desaparecer. Isso é particularmente útil quando seu código contém expressões genéricas ou lambda.Problemas com anotações
Podem surgir problemas quando o seu bloco de código contém uma anotação. Provavelmente porque, quando o
@
sinal aparece no início da linha Javadoc, é considerado uma tag Javadoc como@param
ou@return
. Por exemplo, esse código pode ser analisado incorretamente:O código acima desaparecerá completamente no meu caso.
Para corrigir isso, a linha não deve começar com um
@
sinal:Observe que existem dois espaços entre
@code
e@Override
, para manter as coisas alinhadas com as próximas linhas. No meu caso (usando o Apache Netbeans), ele é renderizado corretamente.fonte
Há uma diferença significativa entre
<blockquote><pre>...
e<pre>{@code....
O primeiro omitirá as declarações de tipo nos genéricos, mas o último o manterá.E.g.: List<MyClass> myObject = null;
exibe comoList myObject = null;
com os primeiros e comoList<MyClass> myObject = null;
com o segundofonte
Se você é um desenvolvedor Android, pode usar:
Para imprimir bem seu código em Javadoc com código Java.
fonte
Tente substituir "código" por "pré". A tag pré em HTML marca o texto como pré-formatado e todos os feeds de linha e espaços aparecerão exatamente à medida que você os digita.
fonte
Acabei de ler a referência do Javadoc 1.5 aqui , e apenas o código com
<
e>
deve ser colocado dentro{@code ...}
. Aqui está um exemplo simples:fonte
Eu incluo meu código de exemplo com
<pre class="brush: java"></pre>
tags e uso o SyntaxHighlighter para javadocs publicados. Não prejudica o IDE e torna bonitos exemplos de código publicados.fonte
Usando o Java SE 1.6, parece que todos os identificadores UPPERCASE PRE são a melhor maneira de fazer isso no Javadoc:
é a maneira mais simples de fazer isso.
Um exemplo de um javadoc que recebi de um método java.awt.Event:
Isso produz uma saída que se parece exatamente com o código regular, com os espaçamentos regulares do código e as novas linhas intactas.
fonte
Pelo menos no Visual Studio Code, você pode forçar um comentário do Javadoc a respeitar quebras de linha envolvendo-o em reticulares triplos, conforme mostrado abaixo:
fonte