Top 10 artigos

Goole
Hotmail
Lista dos países onde o inglês é uma língua oficial
Lista de doenças mentais
Gmail
Família real britânica
Googol
Tuenti
Tsunami
KGB

News:

PHPDoc

PHPDoc é uma adaptação de Javadoc para PHP língua de programação. É um padrão formal para comentar Código de PHP. Oferece três vantagens principais aos estilos comentando genéricos ou aleatórios: Primeiramente, faz comentários readable em programadores incentivando de um método padrão para definir e comentar em aspectos do código que seria ignorado normalmente. Em segundo, permite geradores externos do original como PHPDocumentor para criar formatado bem e fácil de compreender a documentação do API. Em terceiro lugar, reserva algum IDEs como Estúdio de Zend para interpretar tipos variáveis e outras ambigüidades no língua frouxamente datilografada.

PHPDoc suporta a documentação de ambos object-oriented e processual código.

Índices

Componentes de PHPDoc

DocBlock

Um DocBlock é um comentário prolongado de C++-style PHP que comece com “/**” e tenha “*” no começo de cada linha. DocBlocks precede o elemento que estão documentando. Toda a linha dentro de um DocBlock que não comece com o a * será ignorada.

Para documentar a função “foo ()”, coloque o DocBlock imediatamente antes da declaração da função:

/**
 * este é um comentário de DocBlock
 */
foo da função ()
 {
}

Este exemplo aplicará o DocBlock a “define (“mim”, 2); ” em vez de “para funcionar foo ()”:

/**
 * DocBlock para o foo da função?
*
 * O No., este será para a constante mim!
*/
defina (“mim”, 2);
foo da função ($param = eu)
 {
}

defina () indicações, funções, classes, métodos da classe, e vars da classe, inclua () indicações, e as variáveis globais podem tudo ser documentadas, vêem elementos do código de fonte que pode ser documentado

Um DocBlock contem três segmentos básicos nesta ordem:

  • Descrição curta
  • Descrição longa
  • Tag

A descrição curta começa na primeira linha, e pode ser terminada com uma linha em branco ou um período. Um período dentro de uma palavra (como example.com ou 0.1 %) é ignorado. Se a descrição curta se transformar mais de três linhas por muito tempo, only a primeira linha é feita exame. A descrição longa continua para tantas como linhas como desejado e pode conter o markup do HTML para o formato da exposição. Está aqui uma amostra DocBlock com um Short e uma descrição longa:

/**
 * retorne a data de Easter
 *
 * usando a fórmula das “fórmulas que são maneira complicada demasiado para qualquer um
 * compreenda sempre à exceção de mim " por Irwin Nerdy, esta função calcula
 * data de Easter dada uma data no calendário Mayan antigo, se você puder também
 * supõem o aniversário do autor.
*/

Opcionalmente, você pode incluir todos os parágrafos <em um p>< /p> Tag. Tenha cuidado, se o primeiro parágrafo não começar com <o p>, phpDocumentor suporá que o DocBlock está usando o linebreak dobro simples definir rupturas do parágrafo como em:

/**
 * desc curto
 *
 * a primeira sentença da descrição longa começa aqui
 * e continua nesta linha por um quando
 * finalmente conclindo aqui no fim de
 * este parágrafo
 *
 * a linha em branco acima denota uma ruptura do parágrafo
 */

Está aqui um exemplo de usar <p>

/**
 * desc curto
 *
 * <sentença> da descrição longa de p a primeira começa aqui
 * e continua nesta linha por um quando
 * finalmente conclindo aqui no fim de
 * este parágrafo< /p>
* Este texto é ignorado completamente! não é incluído em Tag de p
 * <p> isto é um parágrafo novo< /p>
*/

o phpDocumentor suporta também o formato de DocBlock de JavaDoc através da comando-linha opção - j, --javadocdesc. Devido ao Tag unmatched compliant do non-xhtml p, nós recomendamo-lo altamente evitamos esta sintaxe sempre que possível

/**
 * <p>
* O desc curto realiza-se somente ao primeiro período.
* Isto significa uma sentença como:
* “analisa gramaticalmente o Sr./Sra. fora de $_GET. “
* para analisar gramaticalmente uma descrição curta de “analisa gramaticalmente o Sr.”
 * que é rather silly.  A descrição longa é
 * a descrição inteira de DocBlock including
 * desc curto, e os parágrafos começam onde p é como:
* <p>
* O p acima denota uma ruptura do parágrafo
 */

o phpDocumentor converterá todo o whitespace em um único espaço na descrição longa, rupturas do parágrafo do uso para definir newlines, ou <pre>, como discutidos na seção seguinte.

Detalhes da descrição de DocBlock

Em alguns parsers a descrição longa e curta de um DocBlock é analisada gramaticalmente para alguns Tag seletos do HTML que determinam o formato adicional. Porque não todo o HTML é permitido, serão convertidos geralmente no texto liso ou em mais Tag do específico do índice. Por exemplo, <um b> o Tag pode ser convertido <na ênfase> em DocBook.

Está aqui uma lista dos Tag suportados por PHPDocumentor:

  • <b> -- emfatize/texto bold(realce)
  • <código> -- Use isto cercar o código do php, alguns conversores destacá-lo-á
  • <Br> -- a linha dura ruptura, pode ser ignorada por alguns conversores
  • <i> -- italicize/marca como importante
  • <kbd> -- denote a entrada de teclado/exposição da tela
  • <li> -- artigo da lista
  • <ol> -- lista requisitada
  • <p> -- Se usado incluir todos os parágrafos, se não considerar-se-á texto
  • <pre> -- A linha do Preserve quebra e espaçando, e supõe que todos os Tag são o texto (como CDATA de XML)
  • <samp> -- denote a amostra ou os exemplos (o non-php)
  • <ul> -- lista unordered
  • <var> -- denote um nome variável

Para o caso raro quando o texto “<b> “é necessitado em um DocBlock, use um delimitador dobro como <<em b>>. o phpDocumentor traduzirá automaticamente aquele ao texto físico “<b> “.

Usando <o código> e <pre>

Ambo <código> e <pre> ignore todo o HTML alistado acima à exceção de seus Tag de fechamento </code> para <o código> e </pre> para <pre>

Moldes de DocBlock

A finalidade de um molde de DocBlock é reduzir datilografar redundante. Por exemplo, se um grande número variáveis da classe fossem confidenciais, uma usaria um molde de DocBlock marcá-los como confidenciais. Os moldes de DocBlock aumentam simplesmente todo o DocBlocks normal encontrado no bloco do molde.

Um molde de DocBlock é distinto de um DocBlock normal por seu encabeçamento. Está aqui o molde o mais básico de DocBlock:

/** #@+
 *
 */

O texto que marca este porque um molde de DocBlock é “/** #@+” - todos os 6 caráteres deve estar atual. Os moldes de DocBlock são aplicados a todos os elementos documentable até o marcador do molde do ending:

/** #@-*/

Anote que todos os 8 caráteres devem aparecer como “/** #@-*/” para que phpDocumentor para os reconhecer como um molde.

Página DocBlocks nivelado

Um página-nível DocBlock é o único DocBlock que não pode preceder o elemento que está documentando, porque não há nenhuma maneira preceder uma lima. Para resolver esta edição, a maneira que o phpDocumentor encontra um página-nível DocBlock é analisar gramaticalmente o primeiro DocBlock em uma lima como o página-nível DocBlock, com determinadas circunstâncias.

<? o php
/**
 * Página-nível DocBlock
 */
define (“oops”, “Página-nível DocBlock não é! ”);
?>

Este último exemplo tem um DocBlock, e é o primeiro DocBlock em uma lima, mas não é um Página-nível DocBlock. Como pode o phpDocumentor dizer a diferença entre um Página-nível DocBlock e algum outro DocBlock? Simples:

<? o php
/**
 * finja isto é uma lima
 *
 * Página-nível DocBlock está aqui porque é o primeiro DocBlock
 * na lima, e contem um Tag do @package
 * pagepackage do @package
 */
definem (“quase”, “agora o Página-nível DocBlock é para a página, e definir não tem nenhum docblock”);
?>

Na versão 1.2.2 do phpDocumentor, um Página-nível DocBlock é o primeiro DocBlock em uma lima se contiver um Tag do @package. Entretanto, este exemplo levantará um aviso como ADVERTIR em test.php na linha 8: o Página-nível DocBlock precede “define quase”, usa um outro DocBlock documentar o elemento da fonte. Você pode eliminar o aviso adicionando a documentação definir como segue:

<? o php
/**
 * Página-nível DocBlock
 * pagepackage do @package
 */
/**
 * define DocBlock
 */
define (o “ahhhh”, “agora o Página-nível DocBlock é para a página, e definir DocBlock para definir”);
?>

Agora, a página tem sua documentação, e definir tem sua própria documentação.

Assim, um DocBlock é um página-nível DocBlock SE E SOMENTE SE é ambos:

  1. O primeiro DocBlock em uma lima
  2. Um de:
  3. Contem um Tag do @package
  4. Seguido imediatamente por um outro DocBlock para todo o elemento documentable de PHP isto é deprecado, usa sempre um Tag do @package

Um Página-nível DocBlock pode ter alguns dos Tag padrão do phpDocumentor (veja Tag padrão do phpDocumentor) mais os seguintes Tag:

  • @package
  • @subpackage

o phpDocumentor não documentará uma lima como o primeiro exemplo, lá deve ser pelo menos um elemento documentable de PHP na lima.

Tag

Os Tag são únicas palavras prefixadas “@” por um símbolo. Os Tag informam parsers como apresentar a informação e para modificar a exposição da documentação as well as permita que o IDE defina tipos variáveis. Todos os Tag são opcionais, mas se você usar um Tag, têm exigências específicas analisar gramaticalmente corretamente.

Tag comuns
Tag Uso Descrição
@abstract
@access público, confidencial ou protegido
@author author@email conhecido <do autor>
@copyright data conhecida
@deprecated marca um método como deprecado.
@deprec mesmos que @deprecated
@example /path/to/example
@exception documenta uma exceção jogada por um método - veja também @throws.
@global datilografe $globalvarname
@ignore
@internal informação confidencial para colaboradores avançados
@link URL
@name
@magic
@package
@param datilografe a descrição [$varname]
@return datilografe a descrição Este Tag não deve ser usado para os construtores ou os métodos definidos com a vácuo tipo do retorno.
@see Documenta uma associação a um outro método ou classe.
@since Originais quando um método foi adicionado a uma classe.
@static
@staticvar
@subpackage
@throws Documenta uma exceção jogada por um método.
@todo
@var tipo um tipo de dados para uma variável da classe
@version Fornece o número de versão de uma classe ou de um método.

Além, alguns parsers permitem a duas adições Tag inline: {@id}, usado permitir ligar direto às seções em um tutorial, e {@toc}, usado gerar um índice {@id} de s na lima. Pense de {@id} como <de um name= o " idname "> Tag do HTML como serve à mesma função.

Para mais dentro - a discussão da profundidade de Tag de PHPDoc, vê http://manual.phpdoc.org/HTMLSmartyConverter/PHP/phpDocumentor/tutorial_tags.pkg.html

Pacotes

Para compreender o papel dos pacotes e como usar o @package, é importante saber a lógica atrás de empacotar em PHP. O quest para a programação estruturada conduzida à invenção das funções, então classes, e finalmente os pacotes. Tradicional, um módulo reusável do software era uma coleção das variáveis, das constantes e das funções que poderiam ser usadas por um outro pacote de software. PHP é um exemplo deste modelo, porque há muitas extensões que consistem em constantes e em funções como a extensão do tokenizer. Se pode pensar da extensão do tokenizer como um pacote: é um jogo completo dos dados, das variáveis e das funções que podem ser usados em outros programas. Um formato mais estruturado deste modelo é naturalmente objetos, ou classes. Uma classe contem variáveis e funções. Uma única classe empacota as funções junto relacionadas e as variáveis a reúso.

o phpDocumentor define o pacote em duas maneiras:

  • As funções, as constantes e as variáveis globais são agrupadas nas limas (pelo filesystem), que por sua vez são agrupadas em pacotes usando o Tag do @package em um página-nível DocBlock
  • Os métodos e as variáveis da classe são agrupados nas classes (por PHP), que por sua vez são agrupadas em pacotes em uma classe DocBlock

Estas duas definições do pacote são exclusivas. Ou seja é possível ter classes de um pacote diferente da lima que o contem.

Veja também

Ligações externas

The original article is from Wikipedia. To view the original article please click here.
Creative Commons Licence

 
Custom Search