Context Navigation

Documentação de Código

Conteúdo

Documentação de Código
Referências

O phpDocumentor é o mais utilizado para auto-documentação da linguagem PHP. Similar ao Javadoc, e desenvolvido em PHP, pode ser usado da linha de comando ou através de uma interface web para criar documentação profissional para códigos-fonte PHP. phpDocumentor oferece suporte para relacionar documentações, incorporando documentos de usuário como tutoriais e a criação de código-fonte com destaque visual com referência cruzada para documentação genérica do PHP.

phpDocumentor usa um sistema completo de templates para mudar os comentários do seu código-fonte em formatos mais legíveis e, portanto, úteis. Este sistema permite a criação de documentações de fácil leitura em 15 estilos prontos em versões HTML, PDF, CHM e XML. Você também pode criar seus próprios templates para obter um visual mais próximo do seu projeto.

Elementos documentáveis

O phpDocumentor é capaz de documentar automaticamente comandos include, define, funções, páginas procedurais, classes, seus atributos e métodos. Todos podem conter as tags padrão.

Tags padrão

Dentre as tags disponíveis no phpDocumentor, estas seriam as mais relevantes no contexto do projeto Expresso Livre:

@author [nome_autor]: Autor do elemento atual

@copyright [string]: informações sobre direitos autorais

@deprecated [version/info string]: Elementos abandonados que não devem mais ser usados, podendo ser removidos em futuras versões

@example [arquivo]: Incluir um arquivo externo de exemplo com coloração de sintaxe

@filesource: Similar a @example, porém voltado a arquivos internos

@ignore: Evita a documentação de um elemento

@internal [descrição]: Define descrição de elemento como privada, interna ao projeto e que não deve ser exibida na documentação final

@link [URL link text, URL, URL, URL...]: Mostra um link dentro da documentação

@see [file.ext|elementname|class::methodname()|class::$variablename|functionname()|function functionname Número ilimitado de valores separados por vírgulas]: Link para a documentação de um elemento

@since [version/info string]: Versão a partir da qual um elemento passou a integrar um pacote

@todo [information string]: Modificações a serem feitas

@tutorial [package/ subpackage/ tutorialname.ext #section.subsection description]: Mostra um link para a documentação de um pacote

@uses [file.ext|elementname|class::methodname()|class::$variablename|functionname()|function functionname]: descrição de como o elemento é usado

@version [versionstring]: Versão de um elemento

    Exemplo:
    /**
     * Gerencia o processo básico
     * 
     * @author Carlos Eduardo Nogueira Gonçalves
     * @package  Workflow
     * @license http://www.gnu.org/copyleft/gpl.html GPL 
     */

Tags inline

Diferentemente das tags normais, as tags inline podem ser usadas em qualquer lugar dentro do bloco de comentários.

inline {@link}: Exibe um link para uma URL ou a documentação de algum elemento

{@link URL description }

{@link element description }

inline {@tutorial}: Exibe um link para um tutorial

{@tutorial package/ subpackage/ tutorialname.ext #section.subsection description}

inline {@source}: Exibe o código-fonte de uma função ou método na descrição longa

{@source startline number of lines}

inline {@inheritdoc}: Usada para que as subclasses herdem a descrição detalhada de suas superclasses

{@inheritdoc}

    Exemplo:
    /**
     * Text with a normal @tutorial tag
     * @tutorial phpDocumentor/phpDocumentor.pkg
     */

    Exemplo:
    /**
     * inline tags demonstration
     *
     * this function works heavily with {@link foo()} to rule the world. If I want
     * to use the characters "{@link" in a docblock, I just use "{@}link."  If
     * I want the characters "{@*}" I use "{@}*}"
     */

Elementos procedurais

São considerados elementos procedurais: comandos include, define, funções, e páginas procedurais.

Bloco de comentário em nível de página

Um bloco de página pode ter qualquer uma das tags padrão, e deve obrigatoriamente:

Ser o primeiro bloco em um arquivo;

Conter uma tag @package.

Comandos include/require/include_once/require_once

phpDocumentor extrai o nome do arquivo e tenta ligar a documentação para o respectivo arquivo se possível. Comandos include podem apenas ter as tags padrão.

phpDocumentor tentará localizar o arquivo incluído na lista de arquivos analisados, encontrando-o fará uma ligação para a documentação do arquivo.

Comandos define

O bloco de comentários de uma declaração define poderá conter qualquer tag padrão do phpDocumentor, acrescido da tag:

@name [nome_var]: Especifica um apelido para uma página procedural ou variável global

    Exemplo:
    /**
     * Prefixo das tabelas do workflow
     * @name GALAXIA_TABLE_PREFIX
     */

     define('GALAXIA_TABLE_PREFIX', 'egw_wf_');

Variáveis globais

@global (obrigatória): [datatype $globalvariablename, datatype description]

@name [nome_var]: Especifica um apelido para uma página procedural ou variável global

    Exemplo
    /**
     * Special global variable declaration DocBlock
     * @global integer $GLOBALS['_myvar'] 
     * @name $_myvar
     */

    $GLOBALS['_myvar'] = "myval";

Declaração de funções

@global [datatype $globalvariablename, datatype description]

@param [datatype $paramname description]: Parâmetro de função ou método

@return [datatype description]: Tipo de retorno de função ou método

@staticvar [datatype description]: Uso de uma variável estática dentro de uma função ou método

inline {@source}

    Exemplo:
    /**
     * Includes files from the process folder.
     * @param string $file_name File's name to be included.
     * @return void
     * @license http://www.gnu.org/copyleft/gpl.html GPL
     * @access public
     */

    function wf_include( $file_name )

Classes

@package [nome_pacote]: Agrupa classes, funções e constantes

@subpackage [nome_subpacote]: Agrupa classes, funções e constantes de um pacote

@category [nome_categoria]: Organizar o pacote do elemento documentado

@static: Classe ou método estático

@abstract: Documenta uma classe abstrata, atributo ou método

@license [URL name of license]: Mostra um link para a URL da licença

Os blocos de comentários são herdados pelas classes filhas, variáveis e métodos. As regras para herança são:

As tags @author, @version e @copyright são automaticamente herdadas a não ser explicitamente especificado em contrário;

Embora as tags @package e @subpackage sejam herdadas automaticamente, é recomendado que sejam usadas explicitamente para todas as classes para evitar problemas de conflitos;

Em caso de ausência de descrição breve, ela será herdada;

Em caso de ausência de descrição longa, ela será herdada;

Em caso de haver uma descrição longa e ainda se quiser herdar a descrição da superclasse, use inline {@inheritdoc}

    Exemplo:
    /**
     * Criptografia simples e segura baseada em funções hash   
     * @author	Marc Wöhlken, woehlken@quadracom.de
     * @author	Carlos Eduardo Nogueira Gonçalves
     * @version 1.0
     * @license http://www.gnu.org/copyleft/gpl.html GPL
     * @package Workflow
     */

    class wf_crypt

    Exemplo usando descrição breve e descrição longa:

    /**
     * short desc
     *
     * long desc
     * @package test
     * @author me
     * @version 1.0
     * @abstract
     * @copyright never
     */

Atributos

O bloco de comentário de atributos pode conter qualquer tag padrão e obrigatóriamente a tag @var

@var [datatype $varname descrição]: Um atributo

@access [private, protected, public]: Controle de acesso para um elemento

    Exemplo:
    /**
     * @var	string $hash_key Versão embaralhada da chave de criptografia fornecida pelo usuário
     * @access public
     */

    var $hash_key;

Métodos

@access [private, protected, public]: Controle de acesso para um elemento

@global [datatype $globalvariablename, datatype description]

@param [datatype $paramname description]: Parâmetro de função ou método

@return [datatype description]: Tipo de retorno de função ou método.(Caso retorne mixed especificar quais os tipos possíveis na descrição)

@static: Classe ou método estático

@staticvar [datatype description]: Uso de uma variável estática dentro de uma função ou método

@final: Método que não deve ser sobrescrito nas subclasses

inline {@source}

    Exemplo:
    /**
     * Usado para definir a chave de criptografia e descriptografia
     * @param	string	$key	Chave secreta usada para criptografia e descriptografia
     * @param	boolean	$base64	Usar codificação base64
     * @return void 
     * @access public
     */

    function setKey($key, $base64 = true)

Referências

Manual

Tutorial