Changes between Initial Version and Version 1 of Projeto/PHPDoc

Timestamp:

07/24/07 15:01:45 (17 years ago)

Author:

trac

Comment:

--

Projeto/PHPDoc

@@ +1 @@
+= Introdução =
+ 
+
+O phpDocumentor é o padrão atual de auto-documentação para a 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 dos processo de workflow:
+
+
+
+ * @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]