PHPDocumentor é uma ferramenta escrita em PHP. Para programas PHP com anotações padrão, ele pode gerar rapidamente documentos API com referência cruzada, indexação e outras funções. A versão antiga é phpdoc.
1. O que é phpDocumentor?
PHPDocumentor é uma ferramenta escrita em PHP. Para programas PHP com anotações padrão, ele pode gerar rapidamente documentos API com referência cruzada, indexação e outras funções. A versão antiga é phpdoc. A partir de 1.3.0, foi renomeada como phpDocumentor. A nova versão adiciona suporte para sintaxe php5. Ao mesmo tempo, os documentos podem ser gerados operando no navegador do cliente e os documentos podem ser convertidos para. PDF, HTML, Existem várias formas de CHM, que são muito convenientes.
Quando o PHPDocumentor funciona, ele verifica o código-fonte do PHP no diretório especificado, verifica as palavras-chave, intercepta os comentários que precisam ser analisados, depois analisa as tags especiais nos comentários, gera um arquivo xml e, em seguida, com base nas informações de as classes e módulos analisados, estabelecem índices correspondentes, geram arquivos xml e usam modelos customizados para gerar arquivos no formato especificado para os arquivos xml gerados.
2. Instale o phpDocumentor
Como outros módulos do Pear, a instalação do phpDocumentor também é dividida em dois métodos: instalação automática e instalação manual. Ambos os métodos são muito convenientes:
um. Instale automaticamente através do pear e digite na linha de comando
pera instalar PhpDocumentor
b. Instale manualmente a versão mais recente do PhpDocumentor (agora 1.4.0) em http://manual.phpdoc.org/ e descompacte o conteúdo.
3. Como usar o PhpDocumentor para gerar linha de comando de documentação:
No diretório onde o phpDocumentor está localizado, digite
Php-h
Você obterá uma lista detalhada de parâmetros, vários parâmetros importantes dos quais são os seguintes:
-f O nome do arquivo a ser analisado, vários arquivos separados por vírgulas
-d Diretório a ser analisado, vários diretórios separados por vírgulas
-t caminho de armazenamento do documento gerado
-o O formato do documento de saída, a estrutura é formato de saída: nome do conversor: diretório de modelo.
Por exemplo: phpdoc -o HTML:frames:earthli -f test.php -t docs
A interface web é gerada no novo phpdoc. Além de gerar documentos na linha de comando, você também pode gerar documentos no navegador do cliente. O método específico é primeiro colocar o conteúdo do PhpDocumentor no diretório apache para que possa ser gerado. acessado através do navegador, a seguinte interface será exibida após o acesso:
Clique no botão arquivos para selecionar os arquivos ou pastas php a serem processados. Você também pode ignorar o processamento de determinados arquivos especificando Arquivos a serem ignorados nesta interface.
Em seguida, clique no botão de saída para selecionar o caminho de armazenamento e o formato do documento gerado.
Por fim, clique em criar e o phpdocumentor começará a gerar documentos automaticamente. O progresso e o status da geração serão exibidos na parte inferior.
Tempo total de documentação: 1 segundo
feito
Operação concluída!!
Então, podemos visualizar o documento gerado. Se estiver em formato pdf, o nome padrão é documentação.pdf.
4. Adicione comentários padrão ao código php
PHPDocument gera documentos a partir de comentários em seu código-fonte, portanto, o processo de comentar em seu programa também é o processo de compilação de documentação.
Deste ponto de vista, o PHPdoc incentiva você a desenvolver bons hábitos de programação e tentar usar especificações e texto não criptografado para anotar seu programa. Ao mesmo tempo, evita mais ou menos alguns problemas de dessincronização entre a preparação do documento e o documento. atualiza depois.
No phpdocumentor, os comentários são divididos em comentários de documentação e comentários não documentais.
Os chamados comentários de documentação são comentários de várias linhas colocados antes de palavras-chave específicas. Palavras-chave específicas referem-se a palavras-chave que podem ser analisadas pelo phpdoc, como class, var, etc.
Comentários que não precedem palavras-chave ou não são padronizados são chamados de comentários não documentados. Esses comentários não serão analisados pelo phpdoc e não aparecerão no texto da API que você gerar.
3.2 Como escrever comentários na documentação:
Todos os comentários da documentação são comentários de várias linhas começando com /**, que são chamados de DocBlock no phpDocumentor e se referem às informações de ajuda sobre uma determinada palavra-chave escrita por desenvolvedores de software para que outros possam saber disso por meio dela. e como usá-los. PhpDocumentor especifica que um DocBlock contém as seguintes informações:
1. Área de breve descrição da função
2. Área de descrição detalhada
3. Etiqueta
A primeira linha do comentário da documentação é a área de descrição da função. O texto geralmente explica brevemente a função desta classe, método ou função. O texto da descrição da função será exibido na área de índice no documento gerado. O conteúdo da área de descrição da função pode ser finalizado com uma linha em branco ou após a área de descrição da função, seguida por uma área de descrição detalhada. Esta parte descreve principalmente a função e o propósito de sua API. você também pode exemplos de uso, etc. Nesta seção, você deve se concentrar em esclarecer o propósito geral e o uso de suas funções ou métodos de API e indicar se é multiplataforma (se houver informações relacionadas à plataforma, você deve tratá-las de forma diferente das informações gerais). a abordagem usual é iniciar uma nova linha e, em seguida, escrever as precauções ou informações especiais em uma plataforma específica. Essas informações devem ser suficientes para que seus leitores possam escrever as informações de teste correspondentes, como condições de contorno, intervalos de parâmetros, pontos de interrupção, etc.
Depois disso, há também uma linha em branco e, em seguida, a tag do documento, indicando algumas informações técnicas, principalmente o tipo de parâmetro de chamada, valor e tipo de retorno, relacionamento de herança, métodos/funções relacionados, etc.
Em relação à marcação de documentos, consulte a Seção 4: Marcação de documentos para obter detalhes.
Tags como <b> <code> também podem ser usadas em comentários de documentos. Consulte o Apêndice 2 para obter detalhes.
A seguir está um exemplo de comentário de documentação
/**
* Função add, implementa a adição de dois números
*
* Um cálculo de adição simples, a função aceita dois números aeb e retorna sua soma c
*
* @param int adendo
* @param int summand
* @return inteiro
*/
função Adicionar($a, $b) {
retornar$a+$b;
}
O documento gerado é o seguinte:
Adicionar
inteiro Adicionar(int $a, int $b)
[linha 45]
Função add, implementa a adição de dois números
Constantes é um cálculo de adição simples. A função aceita dois números aeb e retorna sua soma c.
Parâmetros
• int $a - adendo
• int $b - solicitação
5. Marcações de documentos:
O escopo de uso de uma tag de documento refere-se às palavras-chave ou outras tags de documento que a tag pode ser usada para modificar.
Todas as tags de documentação começam com @ após o * em cada linha. Se a marca @ aparecer no meio de um parágrafo, a marca será tratada como conteúdo normal e ignorada.
@acesso
Escopo de uso: classe, função, var, definir, módulo
Esta tag é usada para indicar os direitos de acesso da palavra-chave: privado, público ou protegido
@autor
Especifique o autor
@copyright
Escopo de uso: classe, função, var, definir, módulo, usar
Especifique informações de direitos autorais
@obsoleto
Escopo de uso: classe, função, var, definir, módulo, constent, global, incluir
Indique palavras-chave não utilizadas ou obsoletas
@exemplo
Esta tag é usada para analisar uma parte do conteúdo do arquivo e destacá-la. O Phpdoc tentará ler o conteúdo do arquivo a partir do caminho do arquivo fornecido por esta tag.
@const
Escopo de uso: definir
Usado para indicar as constantes definidas em php
@final
Escopo de uso: classe, função, var
Indica que a palavra-chave é uma classe, método ou atributo final e está proibida de ser derivada ou modificada.
@filesource
Semelhante ao exemplo, exceto que esta tag irá ler diretamente o conteúdo do arquivo php atualmente analisado e exibi-lo.
@global
Indica as variáveis globais referenciadas nesta função
@ingore
Usado para ignorar palavras-chave especificadas no documento
@licença
Equivalente a <a> na tag html, primeiro está o URL e depois o conteúdo a ser exibido, como <a href=”http://www.baidu.com”>Baidu</a>
Você pode escrever @license http://www.baidu.com Baidu
@link
semelhante à licença
Mas você também pode apontar para qualquer palavra-chave no documento através do link
@nome
Especifique um alias para a palavra-chave.
@pacote
Escopo de uso: nível de página -> definir, funcionar, incluir
Nível de classe->classe, var, métodos
Usado para agrupar logicamente uma ou várias palavras-chave em um grupo.
@abstrcut
Indica que a classe atual é uma classe abstrata
@param
Especifique os parâmetros de uma função
@retornar
Especifica o ponteiro de retorno de um método ou função
@estático
Indica que a palavra-chave é estática.
@var
Especifique o tipo de variável
@versão
Especifique informações de versão
@pendência
Indique áreas que devem ser melhoradas ou não implementadas
@lança
Indica a exceção de erro que esta função pode lançar. Em casos extremos, conforme mencionado acima, as tags comuns de documentos devem ser marcadas com @ no início de cada linha. Além disso, há também uma tag chamada tag inline, usando {@ } significa. , incluindo especificamente o seguinte:
{@link }
O uso é o mesmo de @link
{@fonte }
Exibir o conteúdo de uma função ou método
6． Algumas especificações de anotação
a. O comentário deve ser
/**
*XXXXXXXXX
*/
forma
b. Para funções que fazem referência a variáveis globais, a tag glboal deve ser usada.
c. Para variáveis, seu tipo deve ser marcado com var (int, string, bool...)
d. A função deve indicar seus parâmetros e valor de retorno por meio de tags param e return.
e. Para palavras-chave que aparecem duas ou mais vezes, ignore as redundantes por meio de ingore e mantenha apenas uma.
f. Onde outras funções ou classes são chamadas, link ou outras tags devem ser usadas para vincular à parte correspondente para facilitar a leitura do documento.
g. Use comentários não relacionados à documentação quando necessário para melhorar a legibilidade do código.
h. Mantenha o conteúdo descritivo conciso e direto, usando frases em vez de sentenças sempre que possível.
i. Variáveis globais, variáveis estáticas e constantes devem ser declaradas com tags correspondentes.
7. Resumo
phpDocumentor é uma ferramenta de geração automática de documentos muito poderosa. Ele pode nos ajudar a escrever comentários padronizados e gerar documentos claros e fáceis de entender, o que é muito útil para atualizações de código, manutenção, transferência, etc.
Para uma descrição mais detalhada do phpDocumentor, você pode acessar seu site oficial
http://manual.phpdoc.org/View
8. Apêndice Apêndice 1:
Palavras-chave reconhecidas pelo phpdoc:
Incluir
Exigir
include_once
require_once
definir
função
global
aula
Apêndice 2
Tags que podem ser usadas em documentos
<b>
<código>
<br>
<kdb>
<li>
<pré>
<ul>
<samp>
<var>
Apêndice 3:
Um pedaço de código php com comentários canônicos:
<?php
/**
* Arquivo de amostra 2, início rápido do phpDocumentor
*
* Este arquivo demonstra a riqueza de informações que podem ser incluídas em
* documentação no código através de DocBlocks e tags.
* @autor Greg Beaver < [email protected] >
*@versão 1.0
* @pacote amostra
*/
//arquivo de amostra #1
/**
* Valor de inclusão fictício, para demonstrar o poder de análise do phpDocumentor
*/
include_once 'sample3.php';
/**
* Declaração especial de variável global DocBlock
* @global inteiro $GLOBALS['_myvar']
* @nome $_myvar
*/
$GLOBALS['_myvar'] = 6;
/**
*Constantes
*/
/**
* primeira constante
*/
define('teste', 6);
/**
* segunda constante
*/
define('outraconstante', strlen('olá'));
/**
* Um exemplo de docblock de função
* @global string documenta o fato de que esta função usa $_myvar
* @staticvar inteiro $staticvar isso é realmente o que é retornado
* @param string $param1 nome a ser declarado
* @param string $param2 valor do nome
* @return inteiro
*/
function firstFunc($param1, $param2 = 'opcional') {
estático $staticvar = 7;
global $_myvar;
retornar $staticvar;
}
/**
* A primeira classe de exemplo, está no mesmo pacote que a
*coisas processuais no início do arquivo
* @pacote amostra
* @subpackage classes
*/
classe minhaclasse {
/**
* Um exemplo de variável privada, que pode ser ocultada com --parseprivate
*opção
* @acessoprivado
* @var inteiro|string
*/
var $primeiravar = 6;
/**
* @link http://www.example.com Exemplo de link
* @ver minhaclasse()
* @usa teste, outra constante
* @var matriz
*/
var $segundovar =
variedade(
'coisas' =>
variedade(
6,
17,
'tatu'
),
testando => outra constante
);
/**
* O construtor configura {@link $firstvar}
*/
function minhaclasse() {
$this->firstvar = 7;
}
/**
* Retorna uma coisinha baseada em $paramie
* @param booleano $paramie
* @return inteiro|babyclass
*/
function parentfunc($paramie) {
if ($paramie){
retornar 6;
} outro {
retornar nova babyclass;
}
}
}
/**
* @pacote amostra1
*/
class babyclass estende minhaclasse {
/**
* A resposta para a vida, o universo e tudo mais
* @var inteiro
*/
var $segundovar = 42;
/**
* Valores de configuração
* @var matriz
*/
var $terceirovar;
/**
* Chama o construtor pai e depois incrementa {@link $firstvar}
*/
função babyclass() {
pai::minhaclasse();
$this->firstvar++;
}
/**
* Isso sempre retorna um myclass
* @param ignorou $paramie
* @return minhaclasse
*/
function parentfunc($paramie) {
retornar nova minhaclasse;
}
}
?>