Documentation des composants CakePHP

Question

Je m'intéresse principalement à documenter les actions du contrôleur, par exemple http://foo.bar/app/thing/action/param. Comment recommanderiez-vous de les documenter? Je suis moins intéressé par la méthode de génération de la documentation (par exemple phpdoc ou doxygen) et plus un style de le faire. Dois-je énumérer les paramètres et renvoyer les valeurs comme si je documentais une autre méthode?

Answer 1

En termes de format, je suis généralement la même convention (bien, similaire) utilisée par le projet CakePHP lui-même (http://book.cakephp.org/view/509/Coding-Standards#Commenting-code-601). C'est assez similaire à JavaDoc que j'ai trouvé facile à adopter et fonctionne bien avec le moteur phpDoc. J'ai tendance à inclure les valeurs @param ainsi que @return. Je trouve souvent utile de fournir un peu plus d'explications sur les valeurs acceptables/attendues.