Quelqu'un peut-il me dire quelle est la bonne façon de définir les espaces de noms PHP dans la syntaxe phpdoc est? Ou @ @package est déprécié dans phpdoc, puisque les espaces de noms de noms définissent plus ou moins un paquet?
S'il n'y en a pas, existe-t-il un moyen courant de documenter les espaces de noms qu'un document est dans?
4 Réponses :
@package doit être utilisé dans chaque DOCBLOCK de chaque fichier de votre projet, vous pouvez également utiliser @subpackage. @Package n'est pas obsolète et serait la bonne façon de définir vos espaces de noms.
Merci, @subpackage pourrait être utile, mais cela ne résout pas mon problème. +1
phpdoc n'a pas de concept d'espaces de noms, mais vous pouvez (et probablement) utiliser @package pour cela.
Vous pourriez jeter un coup d'œil sur le Documentation phplint pour voir comment ils ' reformez les espaces de noms.
Merci de référencer une bibliothèque existante qui utilise le format d'espace de noms dans leur documentation. Je ne pouvais pas en trouver un, certainement utile!
Manuel PHPDOC est également une bonne ressource
Depuis cette réponse, les choses ont déplacé un peu. PHPDOC utilise maintenant fortement un concept d'espace de noms, mais la documentation phpdoc ne le définit pas car il s'agit d'un concept de langue PHP qui devient contrôlable dans PHP 5.3. La documentation phpdoc recommande maintenant l'utilisation d'espaces de noms sur @package où l'intention est d'avoir la même hiérarchie dans les deux, comme c'est souvent le cas.
Vous pouvez jeter un coup d'œil à Docblox ; Il s'agit d'un générateur de documentation API prenant en charge les espaces de noms.
et pour répondre plus clairement à votre question: autant que j'ai rencontré sont des packages considérés comme obsolètes en raison de l'invention des espaces de noms. Si vous lisez la spécification PSR-0, vous verrez qu'il tente de fournir le package comme deuxième partie d'un espace de noms; premier étant le vendeur.
La documentation phpdoc dit:
La balise @package peut être utilisée comme contrepartie ou complément à Espaces de noms. Les espaces de noms fournissent une subdivision fonctionnelle de la structure Éléments où la balise @package peut fournir une subdivision logique dans de quelle manière les éléments peuvent être regroupés avec une hiérarchie différente.
Si, à travers le tableau, les subdivisions logiques et fonctionnelles sont égal est qu'il n'est pas recommandé d'utiliser la balise @package, pour empêcher frais de maintenance.
https://www.phpdoc.org/docs /Latest/references/phpdoc/tags/package.html