Automatique PHP Génération de documentation?
Pour ActionScript 2, j'ai utilisé NaturalDocs . Cependant, il a un support assez médiocre pour PHP. J'ai regardé jusqu'ici doxygen et phpDocumentor , mais leur sortie est assez moche à mon avis. Quelqu'un at-il une expérience de la génération automatique de documentation pour PHP? Je préférerais pouvoir utiliser des balises de style javadoc, elles sont courtes à écrire et faciles à retenir.
ApiGen
ApiGen prend en charge PHP 5.3 espaces de noms, packages, liaison entre la documentation, références croisées à PHP classes standard et documentation générale, création de code source en surbrillance et support expérimental) pour PHP 5.4 traits.
DocBlox
http://www.docblox-project.org/
Générateur de documentation API compatible PHP 5.3 destiné aux projets de toutes tailles et d'intégration continue.
capable d'analyser et de transformer complètement Zend Framework 2
Il existe deux outils bien connus et souvent utilisés qui peuvent générer un document API à partir de docblocks:
- phpDocumentor , qui est spécifique à PHP, et est probablement l'un des outils les plus utilisés pour les projets PHP
- et Doxygen , qui est plus pour C, mais est utilisé pour PHP par certaines personnes.
À propos des "lignes directrices": Je dirais que cela dépend de vos projets, mais, au moins, je m'attendrais à voir:
- une description de ce que fait la méthode/fonction
- paramètres, avec
@param type name description of the parameter - valeur de retour, avec
@return type description of the return value - exceptions, avec
@throws type description of the exception that can be thrown
Une grande chose étant que la récente IDE (comme Eclipse PDT , par exemple) , peut lire et interpréter ces marqueurs, pour fournir des conseils lorsque vous codez ;-)
En outre, il existe de plus en plus PHP outils qui utilisent les docblocks php à d'autres fins que la documentation.
Par exemple, PHPUnit vous permet de spécifier des éléments liés au test en utilisant des balises spécifiques - voir Annotations .
PHPDoc est probablement aussi bon que vous l'aurez en termes de commentaires en ligne de style Javadoc. Vous pouvez également consulter PHPXRef .
Oui, phpDocumentor ( http://www.phpdoc.org/ ) est un outil standard acceptable pour les autodocs PHP. C'est la norme de facto.
Il est acceptable de suivre les directives générales JavaDoc pour le code lors de la documentation de PHP. Cependant, vous allez rencontrer des cas où cela ne suffit pas car PHP et Java sont des langages différents.
Par exemple, PHP n'ont pas de type de retour et il est inévitable (et parfois souhaitable) qu'une fonction retourne un type avec un contexte, et un autre type avec dans un second contexte. Les directives JavaDoc ne sont pas ' t va aider à cela, car il est impossible de le faire en Java.
Découvrez PHPDoctor http://peej.github.com/phpdoctor/ , un clone Javadoc simple mais complet de fonctionnalités pour PHP.
phpDocumentor peut sortir dans un style similaire à la documentation php.net (et son intégré avec des mises en page smarty et non smarty)
La base de code Wordpress est documentée à l'aide de balises phpdoc (voir this ) et elle est généralement assez bonne - elle est rendue ici utilisant phpDocumentor .
La plupart du code que j'écris est suffisamment substantiel pour que je doive penser à la génération automatique de documents pour est fait dans .Net, donc je ne peux pas donner beaucoup de point de vue d'un auteur de documentation
Si laide est un problème, je changerais simplement la feuille de style pour une personnalisée. Si vous ne voulez pas écraser celui généré, vous pouvez utiliser un plugin Firefox comme Stylish .
Vous pouvez modifier le fichier de modèle pour ajouter votre propre feuille de style pour remplacer celle existante.