J'ai une base de code privée assez importante qui a évolué depuis une dizaine d'années maintenant. Je n'utilise pas phpDocumentor mais depuis que l'utilisation des sections docblock est devenue tout à fait la norme dans les projets open source, j'ai également adopté l'écriture de docblocks pour toutes les méthodes publiques dans mon référentiel. La plupart des blocs contiennent juste une petite description et des indications de type pour tous les paramètres et le type de retour.
Avec l'arrivée de l'analyse statique, ces typographies m'ont beaucoup aidé à trouver des incohérences et des bugs possibles. Dernièrement, j'ai converti l'intégralité de la base de code (en cours d'exécution sur PHP7.2) pour que tous les paramètres et les valeurs de retour soient indiqués dans la mesure du possible, en utilisant les indications de type de PHP. Et maintenant, je me demande ... Est-ce que ces caractères de type docblock ne sont pas redondants? Cela demande un peu de travail pour garder tous les docblocks en synchronisation avec le code en constante évolution et comme ils n'ajoutent aucune nouvelle information, je me demande s'il est préférable de les supprimer complètement ou non.
D'une part, la suppression de la documentation est mauvaise, même lorsqu'elle est redondante. Dans l'autre, j'ai vraiment envie de briser le principe de ne pas répéter soi-même tous les jours qui donne déjà un indice.