Qual é o propósito dessas propriedades do PHPDOC?

Question

Em geral, as propriedades do PHPDOC são autoexplicativas, mas estou tendo dificuldades para entendê-las:

@category - o que é isso exatamente?

@package - alguém poderia me fornecer exemplos sobre o uso desta propriedade?

Answer 1

A tag do pacote é a principal tag de organização que você usa no seu código. Quando o PhpDocumentor gera os documentos, ele coleta elementos nos pacotes que você define. Em alguns casos, você pode optar por usar apenas um nome de pacote (@package mypackage) para toda a sua base de código, de modo que todos os arquivos, classes, etc., apareçam nos documentos desse pacote.

No entanto, se você optar por organizar as coisas de maneira mais modular, poderá ter todos os arquivos processuais voltados para a Web em um pacote (@package webpages), todas as classes voltadas para o banco de dados em um pacote (@package databasehandlers), todas as classes de utilitário em um pacote ( @package utilites) e assim por diante.

A principal coisa a lembrar sobre @package é que é a sua avenida para organização dos documentos... Não tem nada a ver com a forma como o código é executado. Agora, obviamente, é mais provável que você queira organizar os documentos com base em como organizar conceitualmente as peças do seu aplicativo em sua cabeça, para que, nesse sentido, "pacote" gostaria sinto que é organizando o código... Mas, no final, a etiqueta do pacote é sobre como você deseja que o PhpDocumentor organize os documentos.

Quanto à tag de categoria, não acredito que nenhum conversor de saída utilize isso, exceto o (s) que importa para o projeto Pear. A categoria é usada para coletar conjuntos de pacotes em um pacote grande. Mas, novamente, isso é relevante apenas para a pêra, tanto quanto quais capacidades já são assadas nos conversores de saída. Você posso ignore esta tag se quiser ... você não podes Ignore a etiqueta do pacote, porque é essencial para como o PHPDocumentor organiza os documentos.

Agora, quanto aos exemplos de uso do @package, existem alguns no manual, como já mencionado. Para encurtar a história, você precisa de uma etiqueta de pacote no documento de documentos em nível de arquivo de cada arquivo (é daí que funções e constantes escassas globalmente obtriam seu "pacote") e no docblock de todas as classes. Se você não fornecer valores de pacote para esses elementos de código, o PhpDocumortor será forçado a despejar todos eles em um pacote "padrão".

Último ponto ... se você não se importa em organizar seu código em vários pacotes e não deseja editar todos os seus arquivos para adicionar as tags @package, você pode usar o argumento -dn Runtime para definir um pacote padrão nome [1]. Isso informa ao PhpDocumentor para usar o nome do pacote que você fornece nesse argumento para todos os elementos de código "não embalados" para os quais deseja um nome de pacote. Há também um argumento -dc para definir um nome de categoria padrão, mas isso é muito menos crítico, no que diz respeito ao phpdocumentor.

[1] -- http://manual.phpdoc.org/htmlsmartyconverter/hands/phpdocumentor/tutorial_phpdocumentor.howto.pkg.html#using.command-line.defaultPackagename

(Eu estava incluindo mais URLs, mas o Stackoverflow não me deixa postar mais de um ...)

Answer 2

@categoria

A tag @category é usada para organizar grupos de pacotes juntos.

Isso é diretamente aplicável ao conversor XML: DocBook/PearDoc2 e pode ser usado por outros conversores.Outros conversores embalados com phpDocumentor ignoram a categoria, mas isso pode mudar em versões futuras.Também é possível especificar dinamicamente a categoria usando o interruptor -dc, - -DefaultCategoryName Switch

http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.category.pkg.html

@pacote

@package só pode ser usado para documentar páginas ou classes processuais.

Os pacotes são usados ​​para ajudá -lo a agrupar logicamente elementos relacionados.Você escreve classes para funções e dados relacionados ao grupo, e o phpDocumentor representa o conteúdo dos arquivos (funções, define e inclui) como "páginas processuais". Um pacote é usado para agrupar classes e páginas processuais da mesma maneira que um diretório grupos relacionados a arquivos.

http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.package.pkg.html