+- JeuWeb - Crée ton jeu par navigateur (https://jeuweb.org)
+-- Forum : Discussions, Aide, Ressources... (https://jeuweb.org/forumdisplay.php?fid=38)
+--- Forum : Programmation, infrastructure (https://jeuweb.org/forumdisplay.php?fid=51)
+--- Sujet : Comment documentez-vous vos namespace? (/showthread.php?tid=4284)
Comment documentez-vous vos namespace? - Xenos - 27-07-2015
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 ?
RE: Comment documentez-vous vos namespace? - niahoo - 27-07-2015
Pas de doc pour ma part !
RE: Comment documentez-vous vos namespace? - Keltaïnen - 28-07-2015
Moi non plus.
Je pense que ça ne vaut la peine que lorsque le projet est très conséquent, c'est ton cas ?
Si tu parles de documentation de code, je ne vois pas bien quoi te répondre, surtout que tu as visiblement bien creusé le sujet.
Autrement, pourquoi pas la 4e solution avec le fichier à part (1 par namespace) mais dans un répertoire distinct. Ainsi tu pourrais facilement ne pas l'intégrer à ta livraison en production et l'avoir sous la main dans les sources.
RE: Comment documentez-vous vos namespace? - Xenos - 28-07-2015
Pour l'instant, non, c'était une question qui m'est venue en poursuivait la nouvelle version d'eclerd.
Ne pas intégrer le "namespace.ph" à la release, c'est assez simple (suffit de dire à l'outil de release ou de deploy, au choix, d'ignorer ce fichier). Ce qui m'embête, c'est justement de l'avoir en plein milieu de mes sources (dans l'IDE par exemple).
Dans un dossier à part, c'est une alternative, mais cela oblige à reconstruire (et maintenir) l'arborescence des namespaces (au namespace A\B\C correspond l'arborescence A/B/C). Après, ça pourrait être fait par un bout de script ou un plugin de l'IDE...
Quoique je pourrais plutôt les mettre dans mes sources, sous le nom de "namespace.php", et dire à NetBeans de ne pas les afficher (via Tools/Options/Misc/Files/Ignored pattern). Avec un bout de script qui crée le fichier namespace.php dans les dossiers où il n'en 'existe pas (y compris du coup les nouveaux dossiers créés au fil du projet), cela me semble envisageable...
Mais comme tout cela me semble bien lourd pour pas grand chose, je vais faire comme tout le monde: je ne vais pas les documenter
