= Documentação de Código =
[[PageOutline(1-3, Conteúdo)]]

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 =

[http://www.phpdoc.org/manual.php Manual]

[http://www.phpdoc.org/tutorial.php Tutorial]