Aula PHPdoc Prof. Naércio Filho Técnico em Informática www.funpar.ufpr.br:8080/naercio
PHPdoc PHPdoc O Código do PHPdoc deve ser delimitado por /** ...*/ como nos comentários normais porem com um * a mais Se uma linha dentro do bloco não começar com * então será ignorada na interpretação do PHPdoc Bloco de PHPdoc /** * */
PHPdoc Para documentar uma função, constante, classe e etc. O bloco deve ser colocado na linha imediatamente anterior a declaração /** * Esta é a doc de uma função */ function teste(){ // função } deste modo podemos documentar: define() constantes, functions, classes, métodos das classes, variáveis das classes, include() e variáveis globais
PHPdoc - Descrição Curtas Longas /** * Descrição curta * são delimitadas por uma linha em branco, ou um ponto final. Longas é todo o conteúdo de uma descrição /** * Descrição curta * * Descrição completa junto com a anterior, continuando daqui até o fim. * A linha em branco informa uma quebra de parágrafo */
PHPdoc Algumas Tags derivadas do HTML podem ser usadas para formatar a documentação, funcionando como no HTML <b>, <br>, <i>, <li>, <ol>, <ul>, <p>, <pre> outras são especificas: <code> -- Usada para destacar o código em PHP <samp> -- Destaca um trecho de Exemplo <var> -- Destaca um nome de Variável
PHPdoc se uma linha começar com um desses caracteres o PHPdoc pode interpreta-los como uma lista "-", "+", "#", "o" ou um numero seguido de (.) e um espaço em branco, neste ultimo caso cada linha deverá ficar uma abaixo da outra /** * bloco com listas * * +não é uma lista, não tem espaço em branco * Listas * - item 1 * - item 2, linha um * multi linha *- item 3 */
PHPdoc – Templates se houver uma seqüência de dados redundantes podemos usar Templates todas as informações desde o inicio /**#@+ * */ até o termino /**#@-*/
PHPdoc – Templates receberão a mesma PHPdoc /**#@+ * @access private * @var string */ var $_var1 = 'Ola'; var $_var2 = 'PHP'; var $_var3 = 'doc'; /**#@-*/
PHPdoc – Templates retornando algo assim: /** * @access private * @var string */ var $_var1 = ’Ola'; var $_var2 = ’PHP'; var $_var3 = ’doc';
PHPdoc - Tags @abstract Classe / Metodo Abstrato @access Tipo de Acesso, Publico/Privado @author Nome do programador <email> @copyright Informações de Direitos @deprecated Informa quando um método nao é aconselhavel o uso @deprec Apelido para @deprecated @example Caminho para um arquivo contendo um exemplo @exception Compatibilidade com o JavaDoc
PHPdoc - Tags @global descrição das variáveis globais /tipo $globalvar ou @global Variável Global / tipo Descrição da Variavel @ignore Ignorar o Código @internal Documenta Funções internas @param Descrição dos parâmetros /tipo [$var] descrição @return Valor de Retorno / tipo descrição
PHPdoc - Tags @link Link para algum endereço / URL @name Apelido para a pagina @package Documento o Pacote do Script / package nome @see Nome de um outro elemento documentado (cria um link para isso) @since Uma data ou numero de versão @throws Compatibilidade com o JavaDoc @var Define o Tipo da variável / tipo @version Numero de versão
PHPdoc Após o projeto documentado podemos gerar relatórios usando o PHPdoc na linha de comando Na linha de comando um modo seria phpdoc -t /path/to/output -d path/to/directory1,/another/path,/third/path\ -f /path/to/anotherfile.php -i *test.php,tests/ -pp on -ti My Title -o HTML:frames:phpedit onde phpdoc é o aplicativo instalado pode ser encontrado em: http://phpdoc.org/ e os outros dados são parâmetros para a geração, locais de output, onde procurar os arquivos a documentar, titulo, e parâmetros de HTML