Quel est le but de ces propriétés phpdoc?

Question

En général, les propriétés phpdoc sont explicites, mais je vais avoir du mal à comprendre ce:

@category - ce qui est exactement ce

@package - pourrait quelqu'un me donner des exemples sur l'utilisation de cette propriété

?

Answer 1

La balise de package est le porte-clés d'organisation que vous utilisez dans votre code. Lorsque phpDocumentor génère les documents, il recueille des éléments dans les packages que vous définissez. Dans certains cas, vous pouvez choisir d'utiliser un seul nom de package (@package myPackage) pour l'ensemble de votre base de code, de sorte que tous les fichiers, les classes, etc., apparaissent dans les documents de ce paquet.

Toutefois, si vous choisissez d'organiser des choses plus modulairement, vous pourriez avoir tous les fichiers de procédure face à Internet dans un seul paquet (@package pages web), toutes les classes de base de données orientée dans un paquet (DatabaseHandlers de @package), toutes les classes d'utilité dans un emballage (@package Utilites), et ainsi de suite.

L'essentiel à retenir sur @package est que c'est votre avenue pour l'organisation des docs ... il n'a rien à voir avec la façon dont le code est exécuté. Maintenant, évidemment, vous êtes plus susceptible de vouloir organiser les documents en fonction de la façon dont vous organiser conceptuellement les morceaux de votre application dans votre tête, de sorte que dans ce sens, « paquet » serait se sentir comme il est < em> organiser le code ... Mais à la fin, l'étiquette du paquet est tout au sujet de la façon dont vous voulez phpDocumentor organiser les docs.

En ce qui concerne la balise de catégorie, je ne crois pas les convertisseurs de sortie utilisent que, sauf celle (s) que la matière au projet PEAR. Catégorie est utilisé pour regrouper des paquets dans un gros paquet. Mais encore une fois, ce ne concerne que PEAR, pour autant que ce que les capacités sont déjà cuits au four dans les convertisseurs de sortie. Vous peut ignorer cette balise si vous voulez ... vous ne peut pas ignorer l'étiquette de l'emballage, car il est au cœur de la façon dont phpDocumentor organise les docs.

, à des exemples d'utilisation @package, il y en a dans le manuel, comme seengee déjà mentionné. Longue histoire courte, vous avez besoin d'une étiquette de paquet dans le docblock niveau de fichier de chaque fichier (c'est là des fonctions à l'échelle mondiale dans le scope et les constantes obtiendraient leur « paquet » de), et dans le docblock de chaque classe. Si vous ne fournissez pas les valeurs de package pour ces éléments de code, phpDocumentor est obligé de les jeter tout simplement dans un paquet « par défaut ».

Le dernier point ... si vous ne se soucient pas de l'organisation de votre code dans divers paquets, et ne veulent pas modifier tous vos fichiers pour ajouter les balises @package, vous pouvez plutôt utiliser l'argument d'exécution -dn pour définir un nom de paquet par défaut [1]. Cela dit phpDocumentor d'utiliser le nom du package que vous fournissez dans cet argument pour l'ensemble du code « » éléments non emballés qu'il veut un nom de package pour. Il y a aussi un argument -dc pour définir un nom de catégorie par défaut, mais qui est un besoin beaucoup moins critique en ce qui concerne phpDocumentor.

[1] -

Answer 2

@Category

  

La balise @Category est utilisé pour organiser   groupes de paquets ensemble.

     

Ceci est   directement applicable à la   XML: Convertisseur DocBook / de peardoc2, et   peut être utilisé par d'autres convertisseurs. Autre   Convertisseurs fourni avec phpDocumentor   ignorer la catégorie, mais cela peut   changer dans les futures versions. C'est aussi   possible de spécifier de façon dynamique   catégorie en utilisant la -dc,   Commutateur de ligne de commande --defaultcategoryname

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

@package

  

@package ne peut être utilisé pour documenter   pages de procédure ou des classes.

     

Les packages sont utilisés pour vous aider   logiquement des éléments liés à un groupe. Toi   écrire des classes à groupes connexes   les fonctions et les données ensemble, et   phpDocumentor représente le contenu   des fichiers (fonctions, définit et   comprend) en tant que « Pages de procédure ». UNE   emballage est utilisé pour des classes de groupe et   pages de procédure ensemble dans la même   de manière qu'un groupe de répertoires liés   les fichiers ensemble.

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

Answer 3

@Category

  

La balise @Category est utilisé pour organiser   groupes de paquets ensemble.

     

Ceci est   directement applicable à la   XML: Convertisseur DocBook / de peardoc2, et   peut être utilisé par d'autres convertisseurs. Autre   Convertisseurs fourni avec phpDocumentor   ignorer la catégorie, mais cela peut   changer dans les futures versions. C'est aussi   possible de spécifier de façon dynamique   catégorie en utilisant la -dc,   Commutateur de ligne de commande --defaultcategoryname

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

@package

  

@package ne peut être utilisé pour documenter   pages de procédure ou des classes.

     

Les packages sont utilisés pour vous aider   logiquement des éléments liés à un groupe. Toi   écrire des classes à groupes connexes   les fonctions et les données ensemble, et   phpDocumentor représente le contenu   des fichiers (fonctions, définit et   comprend) en tant que « Pages de procédure ». UNE   emballage est utilisé pour des classes de groupe et   pages de procédure ensemble dans la même   de manière qu'un groupe de répertoires liés   les fichiers ensemble.

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