PhpDoc, abreviação de PhpDocumentor, é uma ferramenta poderosa que permite a fácil documentar seu código através de comentários especialmente formatados. A documentação estará disponível não só no código fonte, mas também na documentação profissional extraído usando web ou de linha de comando interface. O resultado pode ser em vários formatos, como HTML, PDF e CHM. Além disso, muitas IDEs que fornecem conclusão de código pode analisar comentários PHPDoc e fornecer recursos úteis, tais como tipo insinuando. Usando phpDoc, você pode torná-lo fácil para os outros (ea si mesmo) para entender seu código - ano semanas, meses, e mesmo depois de você ter escrito.
A maneira mais fácil de instalar phpDoc é com PEAR. Claro, antes que você possa fazê-lo você deve ter PEAR instalado. Se você não fizer isso, siga as instruções em pear.php.net / manual / en / installation.php .
Neste artigo vou mostrar como usar phpDoc para gerar documentação lindo e user-friendly do começo ao fim.
Dockblocks
Um bloco de documentação é um multi-linha de comentário no estilo C usado para documentar um bloco de código. Ela começa com / ** e tem um asterisco no início de cada linha. Aqui está um exemplo:
<? Php
/ **
* Calcula soma dos quadrados de um array
*
* Loops sobre cada elemento na matriz, praças-lo, e adiciona-o
* Total. Retornos totais.
*
* Esta função também pode ser implementado usando array_reduce ();
*
* Param @ array $ arr
* @ Return int
* @ Throws Exception Caso elemento na matriz não é um número inteiro
* /
função sumOfSquares ( $ arr ) {
$ Total = 0;
foreach ( $ arr como $ val ) {
se (! is_int ( $ val )) {
throw novo Exceção ( "O elemento não é um número inteiro!" );
}
$ Total + = $ val * $ val ;
}
retorno total de US $ ;
}
Dockblocks consiste em três seções: descrição curta, longa descrição e tags. Todas as três seções são opcionais.
A breve descrição é uma descrição sucinta denunciado por qualquer nova linha-a ou um período. Rotinas de análise phpDoc são inteligentes, mas só irá terminar a breve descrição que o período seja no final de uma frase.
A descrição longa é onde a maior parte da documentação vai, ele pode ser multi-linha e desde que você desejar.
Ambas as descrições longas e curtas podem conter certos elementos HTML para formatação. Tags HTML que não são suportados serão exibidos como texto simples. PhpDoc pode gerar a documentação em vários formatos, porém, assim que as tags HTML não são necessariamente prestados como fariam em um arquivo HTML, a formatação real depende do formato do arquivo gerado. Se você precisar exibir uma tag HTML como texto, use colchetes duplos. Por exemplo:
<? Php
/ **
* Aqui um exemplo da tag itálico: <<i>> Olá, mundo <<i>>
* /
A seção de tags de um bloco de documentação contém qualquer número de tags especiais indicado pelo @ símbolo. As tags são usadas para especificar informações adicionais, tais como os parâmetros esperados eo seu tipo. A maioria das etiquetas devem estar na sua própria linha, com exceção de alguns códigos que podem ser inline. Tag inline são cercados com chaves e pode ser tanto a descrição da longa e curta. Para obter uma lista completa de tags, confira a documentação pertinente phpDoc .
Se você precisa de começar uma linha com o símbolo @, mas você não quer que ele seja interpretado como uma tag, você pode escapar dele com uma barra invertida.
PhpDoc reconhecerá automaticamente listas textual nas descrições longa e curta e vai analisá-los. No entanto, não irá analisar listas aninhadas corretamente. Se você quiser usar listas aninhadas, use as tags HTML. Aqui está um exemplo para ilustrar o que quero dizer:
<? Php
/ **
* Exemplo de uso de listas
*
* PhpDoc irá analisar esta lista corretamente:
* - Item # 1
* - Item # 2
* - Item # 3
*
* Mas não esta lista:
* - Item 1
* - Item 1.1
* - Item 1.2
* - Item 2
*
* Use isso em vez de uma lista aninhada:
* <ul>
* <li> Item 1 </ li>
* <ul>
* <li> Item 1.1 </ li>
* <li> Item 1.2 </ li>
* </ Ul>
* <li> Item 2 </ li>
* </ Ul>
* /
Pacotes
PhpDoc pacotes são usados para agrupar elementos relacionados com o código na documentação gerada. Você pode especificar pacotes para arquivos e classes eo código documentado que contêm herdarão o pacote a partir deles. Para especificar um pacote, definir o pacote @ tag em um bloco de documentação em nível de arquivo ou em nível de classe (nível de arquivo e em nível de classe dockblocks será discutido é a seção seguinte). Um nome de pacote pode conter letras, números, hífens, sublinhados e colchetes ("[" e "]").
Aqui está um exemplo de definição de pacote de um arquivo:
<? Php
/ **
* Este é um bloco de documentação em nível de arquivo
*
* @ Pacote Some_Package
* /
Se você tem vários níveis de pacotes e sub-pacotes, você pode definir um pacote de sub-com o subpacote @ tag.
Aqui está um exemplo:
<? Php
/ **
* Este é um bloco de documentação em nível de classe
*
* @ Pacote Some_Package
* @ Subpacote Outros
* /
classe SomeClass {
}
Se um arquivo ou classe não especificar um pacote será definido para o pacote padrão, "default". Você pode especificar um pacote diferente para ser usado por padrão ao gerar a documentação via dn- de linha de comando opção.
O que posso documento?
Nem todos os elementos de código pode ser documentado com dockblocks. Aqui está uma lista de elementos de código que podem ser documentados:
Arquivos
Classes
Funções e métodos
Propriedades da classe
Variáveis globais
include () / require ()
define ()
Todos estes elementos pode usar algumas tags comuns, mas cada um tem marcas que são específicos para esse elemento. Eu vou passar por cima de alguns dos elementos e as tags, normalmente usado para documentá-los.
Arquivos
Nível de arquivo dockblocks são usadas para documentar o conteúdo de um arquivo. É altamente recomendável para incluir um bloco de documentação em nível de arquivo em cada arquivo que você documento, e em phpDoc fato irá mostrar um aviso se um não for encontrado ao gerar documentação.
A maioria dos elementos são documentados pela colocação de um bloco de documentação antes do elemento, mas os arquivos são uma exceção (desde que você não pode escrever qualquer coisa antes de um arquivo). Nível de arquivo dockblocks são colocados na primeira linha do arquivo.
Um bloco de documentação em nível de arquivo normalmente contém os tags @ pacote , subpacote @ , @ licença , e @ autor . O pacote de @ e @ subpacote etiquetas foram discutidos anteriormente. A licença @ tag é usado para especificar uma URL para uma licença de externas, que abrange o seu código. A tag deve conter a URL para a licença e, opcionalmente, um título. O autor @ tag é usado para especificar o autor do arquivo. Ele deve conter o nome do autor e, opcionalmente, um endereço de e-mail no ângulo entre parênteses.
Diferentemente da maioria dos elementos, um bloco de documentação em nível de arquivo deve conter um pacote @ tag, a fim de ser analisado corretamente.
Aqui está um exemplo completo de um bloco de documentação em nível de arquivo:
<? Php
/ **
* Este arquivo contém funções comuns usados em todo o aplicativo.
*
* @ Package MyProject
* @ Subpacote Comum
* @ Licença http://opensource.org/licenses/gpl-license.php GNU Public License
* @ Author Moshe Teutsch <moteutsch@gmail.com>
* /
Classes
Um bloco de documentação em nível de classe é colocado antes de uma definição de classe e deve descrever o significado da classe. Como nível de arquivo dockblocks, em nível de classe dockblocks geralmente contêm as tags @ package , @ subpacote e @ autor . Aqui está um exemplo:
<? Php
/ **
* Uma classe de exemplo
*
* A classe está vazia por causa deste exemplo.
*
* @ Package MyProject
* @ Subpacote Comum
* @ Author Moshe Teutsch <moteutsch@gmail.com>
* /
class Exemplo {
}
Funções e métodos
Funções e métodos são documentados de forma idêntica em phpdoc. (Para aqueles que podem não estar familiarizados com a terminologia, um método é apenas uma função dentro de uma classe.) Funções e métodos geralmente contêm o @ param e @ return tags em sua dockblocks. O @ param tag é usada para documentar o tipo esperado de um parâmetro. Ela contém três seções: o parâmetro, o tipo de dados e uma descrição opcional. O @ return tag é utilizado para documentar o tipo de retorno. Ele contém duas seções: o tipo de dados e uma descrição opcional. Em ambos os tags, o tipo de dados pode ser um válido PHP tipo de dados, um nome de classe, ou "mista". Ele também pode conter múltiplas opções separadas por um tubo.
<? Php
/ **
* Localiza e retorna usuário por ID ou nome de usuário
*
* @ Param int $ user | Ou cadeia de identificação ou um nome de usuário
* @ Param $ pdo DOP Um objeto PDO válido
* @ Return Usuário objeto Usuário Retorna ou nulo se não for encontrado
* /
função getUser ( $ user , PDO $ pdo )
{
/ / ...
se ( $ isFound ) {
retorno novas Usuário (...);
}
retorno null;
}
Documentação gerando
Uma vez que você documentou o seu código PHP, você vai querer gerar user-friendly documentação dele. Para isso, executar a ferramenta de linha de comando phpdoc.
~ $: moteutsch @ vivaldi 'Título' Documentação phpdoc-d / path / to / files /-t / path / to / docs /-ti-dn "Pacote Padrão '-o HTML: frames: default
O -d opção especifica uma lista separada por vírgula de diretórios que contêm arquivos para documentos, e -t o caminho para docs gerado. -ti é usado para especificar o título do projeto, e -dn para definir o nome do pacote padrão. Finalmente, -o especifica o formato de documentação. PhpDoc tem uma vasta selecção de formatos para escolher. A lista completa está disponível no website phpDoc .
Você pode descobrir mais sobre a ferramenta de linha de comando executando o comando de ajuda da seguinte forma:
moteutsch @ vivaldi: ~ $ phpdoc-h
Uma vez que você executar o comando, o caminho que você especificou documentação deverá conter os documentos gerados.
Para aqueles de vocês que não estão confortáveis usando a interface de linha de comando, phpDoc também tem uma interface web disponível. É fora deste âmbito artigos para discuti-lo durante um tempo, mas você pode ler mais sobre ele no site oficial do phpDoc, phpdoc.org .
Nenhum comentário :
Postar um comentário