27-07-2015, 08:12 PM
Salut à tous!
Je croise un petit soucis niveau documentation de projet... Pour les classes, les méthodes, les membres, les variables, etc pas de soucis: la documentation va là où l'entité est déclarée (en PHP, on n'est même pas em*rdé par des .hpp vs .cpp).
Mais pour les namespace? Où les documenter?
→ Le même namespace revient sur différents fichiers, donc il me semble difficile de documenter le namespace à chacune de ses occurrences (cela reviendrait à mettre la même documentation à chaque fois que le namespace est utilisé, donc doublons donc in-maintenable).
→ Le documenter que sur une seule occurence d'un namespace donné me semble délicat: dans quel fichier ira cette documentation? Cela impliquerait qu'un des fichiers contiendrait une documentation supplémentaire (celle du namespace) que n'aurait pas les autres.
→ Ou alors, éclater la documentation à différents endroits où un même namespace est utilisé? Chaque utilisation du namespace pourrait alors venir avec sa propre pierre à amener à la documentation de ce namespace? Mais cela me semble difficile à gérer (j'ai déjà du mal à décrire ce principe, alors l'appliquer sur le long terme).
→ Sinon, je pourrai créer un fichier par namespace avec uniquement sa documentation. C'est mieux structuré, mais cela implique d'avoir des fichiers qui ne contiennent que la documentation du namespace: cela pollue un peu les sources.
→ Ou alors, il faudrait centraliser tous les namespaces dans un seul fichier, et documenter dans ce fichier, mais là, c'est la scalabilité qui me semble problématique: j'ai peur de vite me retrouver avec un fichier PHP de documentation pure qui fait des dizaines de milliers de lignes (puisqu'il regroupe tous les namespaces avec leur documentation).
Alors du coup, pour documenter les espaces de nom, vous faites comment vous? Si vous ne les documentez pas (c'est aussi envisageable), est-ce que cela reste quand même viable ?
Je croise un petit soucis niveau documentation de projet... Pour les classes, les méthodes, les membres, les variables, etc pas de soucis: la documentation va là où l'entité est déclarée (en PHP, on n'est même pas em*rdé par des .hpp vs .cpp).
Mais pour les namespace? Où les documenter?
→ Le même namespace revient sur différents fichiers, donc il me semble difficile de documenter le namespace à chacune de ses occurrences (cela reviendrait à mettre la même documentation à chaque fois que le namespace est utilisé, donc doublons donc in-maintenable).
→ Le documenter que sur une seule occurence d'un namespace donné me semble délicat: dans quel fichier ira cette documentation? Cela impliquerait qu'un des fichiers contiendrait une documentation supplémentaire (celle du namespace) que n'aurait pas les autres.
→ Ou alors, éclater la documentation à différents endroits où un même namespace est utilisé? Chaque utilisation du namespace pourrait alors venir avec sa propre pierre à amener à la documentation de ce namespace? Mais cela me semble difficile à gérer (j'ai déjà du mal à décrire ce principe, alors l'appliquer sur le long terme).
→ Sinon, je pourrai créer un fichier par namespace avec uniquement sa documentation. C'est mieux structuré, mais cela implique d'avoir des fichiers qui ne contiennent que la documentation du namespace: cela pollue un peu les sources.
→ Ou alors, il faudrait centraliser tous les namespaces dans un seul fichier, et documenter dans ce fichier, mais là, c'est la scalabilité qui me semble problématique: j'ai peur de vite me retrouver avec un fichier PHP de documentation pure qui fait des dizaines de milliers de lignes (puisqu'il regroupe tous les namespaces avec leur documentation).
Alors du coup, pour documenter les espaces de nom, vous faites comment vous? Si vous ne les documentez pas (c'est aussi envisageable), est-ce que cela reste quand même viable ?
