PHPDocumentor

Usando documentação externa

Enviado por Yukare em terça-feira, 8 de Agosto de 2017 - 16:04

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.

Tags HTML

Enviado por Yukare em terça-feira, 8 de Agosto de 2017 - 15:13

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

Opções da linha de comando

Enviado por Yukare em terça-feira, 8 de Agosto de 2017 - 15:06

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.

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

Descrição das tags

Enviado por Yukare em terça-feira, 8 de Agosto de 2017 - 14:49

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.

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:

Como documentar o código

Enviado por Yukare em terça-feira, 8 de Agosto de 2017 - 14:46

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:

Instalação

Enviado por Yukare em domingo, 6 de Agosto de 2017 - 19:50

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.

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)

PHPDocumentor

Enviado por Yukare em quinta-feira, 3 de Agosto de 2017 - 20:27

O que é o phpDocumentor? O que ele pode fazer?

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.

phpDocumentor é uma ferramenta escrita em php desenvolvido para criar uma documentação completa direto do código fonte php e de documentação externa. A verdade é, o código php é tão claro que ele praticamente serve como sua própria documentação. phpDocumentor interpreta todos os tipos de estruturas lógicas já encontradas no PHP como arquivos, classes, funções, definições de constantes, variáveis globais, e funções/métodos de classe e os organiza em um formato de manual tradicional. Em adição, a partir da versão 1.3.0, elementos do código fonte introduzidos no php 5(constantes de classe, interfaces e outros) também podem ser interpretados, se o phpDocumentor for executado no PHP 5.