Importante: escrevi toda esta documentação há um tempo atrás para a versão 1.4.3 do phpDocumentor. No entanto agora existe a versão 2. Acredito que quase tudo escrito aqui se aplica também a versão 2, mas ainda preciso revisar todo este conteúdo para corrigir qualquer eventual diferença.
Usando tags HTML
A partir do phpDocumentor 1.2.0, a descrição longa e curta do bloco de documentação é interpretada para algumas poucas tags HTML que determinam formatação adicional. Devido a natureza de múltiplos formatos de saída do phpDocumentor, HTML puro não é permitido em um bloco de documentação, e será convertido para texto simples por todos os conversores a menos que seja uma das seguintes tags:
- <b> -- texto com enfâse/negrito
- <code> -- Use isto para marcar código php, alguns conversores irão destaca-lo
- <br> -- quebra de linha, pode ser ignorado por alguns conversores
- <i> -- itálico/marcar como importante
- <kbd> -- marca entrada de teclado/saída de tela
- <li> -- item de lista
- <ol> -- lista ordenada
- <p> -- Se usado para marcar todos os paragrafos, se não será considerado texto
- <pre> -- Preserva quebras de linhas e espaçamento, e assume que todas as tags são texto(parecido com o CDATA do XML)
- <samp> -- Denota exemplos (não php)
- <ul> -- Lista não ordenada
- <var> -- Denota o nome de uma variável
Não pense nestas tags como texto, elas são convertidas para objeto e convertidas para o formato de saída apropriado pelo conversor. Assim, uma tag <b> se torna <emphasis> em DocBook, e uma tag <p> se torna " " (quatro espaços) no conversor PDF. A saída de texto é determinada pelas opções de template no arquivo options.ini encontrado no diretório base de todos os template.
Para o caso raro quando o texto "<b>" é necessário em um bloco de documentação, use um delimitador duplo como em <<b>>. O phpDocumentor irá altomaticamente traduzir no texto <b>.
Similarmente, se você precisa usar "@" em um bloco de documentação, você deve ter o cuidado para que não seja o primeiro caractere em uma linha, ou então escapa-lo "\@" (colocando uma barra invertida \ antes de @) para prevenir que seja interpretado como uma tag de marcação do phpDocumentor
/** * Demostra a utilização de @include * dentro de um bloco de código: * * <code> * \@include somefile.php * </code> */
Isto será interpretado como se fosse:
/** * Demonstra a utilização de @include * dentro de um bloco de código * * <code> * @include somefile.php * </code> */
As tags <code>, <kbd>, e <pre> ignoram qualquer html listado acima exceto por suas proprias tags de fechamento(</code> </kbd> </pre>). Isto é obviamente necessário para cada uma dessas tags poder controlar a aparência do texto dentro do seu bloco, sem permitir que outras tags aninhadas(exemplo <b>) interfiram dentro delas. Em geral, as outras tags permitiram que tags sejam aninhadas com elas (exemplo <samp><b>negrito_no_exemplo</b></samp>).
A partir do 1.2.0rc1 se você necessita colocar um comentário de fechamento "*/" em um bloco de documentação, use a sequencia especial de escape "{@*}." Aqui esta um exemplo:
/** * Simple DocBlock with a code example containing a docblock * * <code> * /** * * My sample DocBlock in code * {@*} * </code> */
Isto será interpretado como se fosse:
/** * Bloco de documentação simples contendo um bloco de documentação como exemplo * * <code> * /** * * Meu bloco de exemplo no código * */ * </code> */
A ferramenta phpEdit suporta uma maneira simples de extração de listas de blocos de documentação, e agora o phpDocumentor suporta a mesma simplicidade. Este exemplo:
/** * Bloco de documentação simples com uma lista simples * * Aqui esta uma lista simples: * - item 1 * - item 2, este aqui * é de múltiplas linhas * - item 3 * Fim da lista. A próxima é ordenada * 1 item ordenado 1 * 2 item ordenado 2 * Fim da lista. Esta também é ordenada: * 1. item ordenado 1 * 2. item ordenado 2 */
phpDocumentor reconhece qualquer lista simples que começa com "-", "+", "#" e "o", e qualquer lista ordenada com número sequenciais ou números seguidos por "." como acima. Este delimitador de lista deve ser seguida por um espaço(não um tab) e os espaços em branco devem se alinhar exatamente, ou o phpDocumentor não irá reconhecer os itens da lista como sendo da mesma lista.
/** * Simple DocBlock with screwy lists * * +not a list at all, no space * Here's 3 lists! * - item 1 * - item 2, this one * is multi-line *- item 3 */
Novamente, você deve alinhar os marcadores de lista na mesma coluna vertical para que os itens da lista sejam considerados da mesma lista. Também, você não pode criar listas aninhadas usando estes simples marcadores de lista ... fazendo assim significa que não é mais uma lista simples. A variação dos espaços dos marcadores de lista não cria listas aninhadas, ele simplesmente cria listas novas. Se você precisa especificamente de listas aninhadas, use as tags (<ol>, <ul>):
/** * DocBlock with nested lists * * Here's the "complex" list: * <ul> * <li>outer item 1</li> * <li>outer item 2, this one * is multi-line</li> * <li>item 3 is a nested inner list * <ul> * <li>inner item 1</li> * <li>inner item 2</li> * </ul> * <li>outer item 4</li> * </ul> */
Em alguns casos, o texto de descrição de uma tag de documentação pode conter uma lista, seja simples ou complexa. Note que uma linha de titulo é necessária, com os itens da lista começando na linha a seguir:
/** * DocBlock with nested lists * in the tag descriptions * @todo My Simple TODO List * - item 1 * - item 2 * - item 3 * @todo My Complex TODO List * <ol> * <li>item 1.0</li> * <li>item 2.0</li> * <li>item 3.0</li> * <ol> * <li>item 3.1</li> * <li>item 3.2</li> * </ol> * <li>item 4.0</li> * </ol> */
As listas com tags são sempre uma opção mais robusta e previsível para você usar. Listas simples são convenientes, mas se você se encontrar tentando fazer uma lista simples se parecer de uma forma especifica quando estiver gerando a documentação, você será melhor servido se usar uma lista com tags.