Quelle est la meilleure façon de documenter les changements dans une fonction avec PHPDoc? Quelque chose commePHPDoc Function Changelog (@change?)
@change 2010.20.16 user added feature x
@change 2010.20.26 user added feature y
serait génial. Mais supposons qu'il n'y ait pas d'option @change ... Si je l'ajoute de toute façon, que va faire PHPDoc avec? Ou existe-t-il une meilleure façon de documenter les changements de fonction?
Il serait peut-être préférable de simplement vider votre journal SCM dans un fichier txt changelog, puis essayez de l'intégrer dans le code source.
Raisons pour lesquelles:
Présomption - Il ne fera pas de bien à personne si vous arrêtez d'ajouter des notes de changement qui est susceptible de se produire si avoir à aller sur un marathon de codage/sprint de malheur.
Non conventionnel - Je ne me souviens pas d'avoir vu un projet avec cette documentation en profondeur. Parfois, les conventions sont carrément stupides, mais je pense que la sagesse de celui-ci réduit la maintenance.
+1. La méthode SCM a l'avantage de lier le message de validation aux modifications appliquées. Les commentaires en ligne comme le PO suggère ne montrerait pas réellement les changements associés. –
* (référence) * http://manual.phpdoc.org/HTMLframesConverter/default/ – Gordon