PhpDocumentor

PhpDocumentor - Usando Documentação Externa

Enviado por Yukare em Qua, 19/07/2023 - 00:40

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.

Escrevendo documentação externa e criando links da documentação do código fonte.

Mesmo sendo a documentação interpretada direto do fonte muito útil, ela não pode suportar por sí só. Em adição, documentação verdadeiramente útil deve ser sucinta o suficiente, se não o código fonte é obscurecido pela documentação. Documentação externa é um dever para uma solução de documentação completa. Entretanto, a documentação externa deve ser ligações com a documentação da API para ser útil. Com as constantes mudanças da documentação da API, é muito fácil para a documentação externa se tornar desatualizada. Além disso, a documentação externa deve estar em um formato que possa ser convertido para outros formatos como HTML, PDF e XML.

phpDocumentor prove uma simples e elegante solução para este problema. Documentação externa do formato DocBook pode ser facilmente convertida para outros formatos. Usando tags inline, o phpDocumentor pode gerar um manual consistente em vários formatos combinando a saída da interpretação do código fonte com a documentação externa.

PhpDocumentor - Tags HTML

Enviado por Yukare em Qua, 19/07/2023 - 00:39

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:

PhpDocumentor - Opções da linha de comando

Enviado por Yukare em Qua, 19/07/2023 - 00:37

Esta é uma lista das opções em linha de comando aceitas pelo phpdoc, várias destas opções podem ter mais de um argumento como nomes de arquivos e diretórios, neste caso são separados por "," (vírgula).

-c --config

Faz com que seja utilizado um arquivo de configuração. Vou explicar mais sobre isso em outra pagina, para mim essa é a melhor maneira de usar do que ficar especificando a cada vez as opções que eu quero.

-cp --converterparams

Define dinamicamente parâmetros para um conversor, separe os valores com virgulas

-ct --customtags

Uma lista separada por virgula de @tags que não sejam padrões para passar para o conversor como válidas(quando você adiciona suas próprias tags)

-d --directory

Nome do diretório(s) a serem interpretados

-dc --defaultcategoryname

Nome da categoria padrão, se não for especificado usa 'default'

-dh --hidden

Define como on (-dh on) para que diretórios ocultos também sejam interpretados (diretórios que começam com "."), o padrão é off (diretórios ocultos não serão interpretados).

-dn --defaultpackagename

Nome do pacote padrão, se não for especificado será usado 'default'

-ed --examplesdir

Caminho completo do diretório onde procurar os arquivos de exemplo das tags @example.

-f --filename

Nome dos arquivos a interpretar. Pode ser um caminho completo e pode se utilizar os coringas * e ?.

PhpDocumentor - Instalação

Enviado por Yukare em Qua, 19/07/2023 - 00:36

Existem dois métodos oficiais. O primeiro e através de copiar e extrair um dos arquivos disponíveis em http://sourceforge.net/projects/phpdocu/files (atualmente na versão 1.4.3), e a outra é através do instalador PEAR. É importante notar que a instalação funciona da mesma maneira, tanto no Windows quanto no Linux, para as duas opções existentes.

Instalação através de um arquivo copiado

Para instalar o phpDocumentor a partir de um arquivo zip copiado diretamente de sourceforge.net, primeiro determine se você estará usando a interface via web ou a interface de linha de comando(acho a interface de linha de comando bem mais pratica de usar, embora levemente mais complicada de usar)

Para usar a interface de linha de comando, descompacte o arquivo em qualquer diretório, por exemplo, /home/myuser/phpdoc ou C:\phpdoc, e adicione este diretório ao seu PATH. Para executar, use o comando "phpdoc". No windows você vai precisar editar o arquivo the phpdoc.bat, e mudar a primeira linha para o caminho da versão CLI do seu PHP (normalmente C:\php4\cli\php.exe por padrão).

Você também pode fazer assim, supondo que você tenha o php instalado em c:\php, e que tenha descompactado o arquivo zip do phpdoc em c:\phpdoc, abra uma janela do prompt de comando, nesta janela do prompt de comando digite:

phpDocumentor - Descrição das tags

Enviado por Yukare em Seg, 17/07/2023 - 18:29

Aqui estão todas as tags, ainda preciso descrever melhor algumas delas, assim como pretendo logo colocar exemplo em todas.

Esta é uma lista das tags e o que elas descrevem:

@abstract

Use a tag @abstract para declarar um método, variável de classe, ou classe que deva ser redefinida em uma classe filho para ser válida.

@access

Controla o acesso ao próximo elemento. Se @access é private, o elemento não será documentado a menos que a opção de linha de comando --parseprivate seja especificada.

@author

A tag @author é usada para documentar o autor de qualquer elemento que possa ser documentado. O phpDocumentor irá pegar qualquer texto entre maior que e menor que (< and >) e tentar interpretar como um endereço de email criando um link na pagina para enviar email, exemplo:

/**   
*@author Fernando Conceição <conceicao.fernando@gmail.com>
*/

@category

A tag @category é usada para organizar grupos de pacotes juntos. Isto é diretamente aplicável ao conversor XML:DocBook/peardoc2 e pode ser usado pelos outros conversores. Outros conversores embutidos no phpDocumentor ignoram a categoria, mas isso pode mudar em versões futuras. Também é possível especificar dinamicamente a categoria usando a opção de linha de comando -dn, --defaultcategoryname

@copyright

A tag @copyright é usada para documentar as informações de direitos autorais de qualquer elemento que possa ser documentado. O phpDocumentor irá exibir o conteúdo desta tag sem nenhuma alteração.

phpDocumentor - Como documentar o código

Enviado por Yukare em Seg, 17/07/2023 - 18:10

Documentando seu fonte PHP com comentários

Todos os blocos de documentação são um comentário no estilo C com dois asteriscos após a barra, como mostrado abaixo:

/**  
 *
 */

Todos os outros comentários são ignorados pelo interpretador da documentação. Note que mesmo sendo quase toda a documentação escrita em texto puro, existem alguns caracteres "@" flutuando pelo código fonte. Este símbolo é usado como um comando especial para o interpretador, e é chamado de tag. Se o símbolo esta no início da linha, é uma tag padrão, se esta contido em {chaves}, é uma tag inline.

/**
 * {@inlinetag}
 * esta @não é uma tag padrão - deve iniciar uma linha.
 * isto é valido também {@inlinetag}
 * @tagpadrão
 */

Documentando variáveis globais

Veja este exemplo de código:

/**
 * Bloco de documentação especial para variáveis globais
 * @global integer $GLOBALS['_myvar']
 * @name $_myvar
 */ 
$GLOBALS['_myvar'] = 6;

Neste segmento, você pode ver duas tags importantes ao documentar variáveis globais. A tag $global é usada para indicar ao interpretador como encontrar a declaração de uma variável global. Sem esta tag, não será gerada documentação para $_myvar. A tag @global pode ter várias formas - tenha certeza de especificar o tipo e o nome global, sem descrição, ou o interpretador irá gerar um aviso e falhar na interpretação da variável global. Avisos de bloco de documentação a nível de pagina

Inscrever-se em PhpDocumentor