Documentation développeur
Modéle objet de WikiNi
Ancienne discussion sur la classe Wiki:
ObjetsDeWakkaPhp
Excellente initiative ! En revanche, je pense qu'il est très important de changer le nom de la page : il existe en effet un moteur de wiki qui s'appelle
PhpWiki : il ne faut pas que cela prête à confusion. Je propose :
ClassesPhpDeWikiNi? ou
ModeleObjetDeWikiNi. Il serait en outre intéressant de compléter avec des exemples, comme sur la page
NotesProgrammation. --
CharlesNepote
Génial ça va beaucoup m'aider pour ma créations d'action.
--
Nicephore17
- Puis j'ai décomposé en sous page en prévision de l'ajout progressif des autres objets (actions, méthodes, etc ...). Les exemples viendront après et notamment de NotesProgrammation -- OlivierB
Suggestions
Dans la suite de cette documentation, je propose que l'on crée une page
ArborescenceDeWikiNi? détaillant chaque fichier (dans des pages nommées FichierNomDuFichier avec ou sans l'extension, eventuellement DossierNomDuDossierFichierNomDuFichier, par exemple DossierActionsFichierTrail), son utilité, son fonctionnement, les autres fichiers qu'il utilise (includes etc.), et les diverses constantes, classes et fonctions qu'il déclare (avec des liens vers les pages de description des classes et fonctions en question). Mais en fait je ne sais pas trop si c'est intéressant de détailler les autres fichiers que wakka.php... Je pense que ça peut tout de même être intéressant pour quelqu'un qui, comme moi, essaie de comprendre un peu le fonctionnement de chaque chose. --
LordFarquaad
- Alors pas d'avis sur ce que j'avais proposé là ? Je me rends compte que ça pourrait aussi beaucoup aider le développement de WikiNi: améliorations, performances, éventuellement détection de bugs... Il serait beaucoup plus facile de parler de cela dans des pages spécifiques aux fichiers concernés. Par exemple je viens d'ouvrir un fichier au hasard: formatters/action.php. Déjà, aucune documentation. Je devine sans trop de mal qu'il s'agit du fichier qui s'occupe de détecter les actions et de les exécuter, mais ce n'est tout de même pas pratique d'avoir à lire le code pour savoir ce qu'il fait... Par ailleurs, je me rends compte qu'il y a pas mal d'aberrations, mais où en faire part ? (pour info, à mon sens, ce fichier pourrait ne faire que... 3 lignes !) -- LordFarquaad
- ÀMHA ce fichier là n'est plus utilisé depuis longtemps ! Je n'avais même pas remarqué sa présence, ce qui veut dire que je n'ai jamais eu besoin de le patcher depuis un an ; or j'ai pourtant déjà patché quasiment tous les fichiers pour mon Wiki professionnel... Les actions sont actuellement détectées par formatters/wakka.php, comme tout le reste, qui appelle ensuite Action() dans wakka.php. -- ProgFou
- Ca sert, c'est appellé par le handler xml.php -- DavidDelon [Quelle page dois-je lire pour comprendre comment on en est arrivé à cette implémentation pour le moins curieuse ? -- ProgFou] [Comment ça curieux ? voir ProduireDesFilsRSS, il y a une argumentation, de ma part, sur ce nouvel handler (cf question de CharlesNepote : pourquoi avoir choisi un nouvel handler ?). Cela dit, Wikini a évolué (handler modulaire) et, si de plus, tu estimes que l'on peut se passer de action, n'hésite pas à sabrer. -- DavidDelon
- D'accord pour une documentation des fichiers mais sur une seule page. ProgFou a raison de souligner qu'après il faut pouvoir maintenir la doc... Si on est obligé de modifier 15 pages à chaque modification du code ça va vite devenir lourd et ça va décourager des développeurs. Documenter : ok, mais sans pénaliser le dév. Je trouve que la procédure de développement publiée dans DeveloppementDeWikini est déjà assez lourde. -- CharlesNepote
- Sur une seule page ? Elle risque d'être très longue ou alors les descriptions très (trop...) consises à mon avis, et ça va vite être le bl si on commence à discuter dessus... Par contre je ne pense pas qu'en faisant une page par fichier on ait à modifier 15pages à la moindre modification du code, ce serait uniquement pour les modifications majeures (ajout/modification/suppression de classes, fonctions, constantes... et changements dans le fonctionnement d'un fichier) et ça ne ferait jamais qu'une page à modifier... -- LordFarquaad
Pourquoi ne pas documenter directement le code source en suivant les recommandation de
phpDocumentor ? L'avantage est que le code est documenté et donc un éventuel développeur n'a pas à regarder les pages de
WikiNi pour comprendre ce qui se passe. Ensuite, phpDocumentor permet de générer facilement une documentation en HTML/CHM/PDF qui pourrait être téléchargée par les développeurs. --
GarfieldFr
- +1, je l'avais déjà proposé dans l'ancienne page ObjetsDeWakkaPhp. -- LordFarquaad
- Je pense que c'est la meilleur solution car la documentation est alors intimement liée au code source et donc toujours à jour. La maintenance d'une documentation externe provoque forcément une différence entre l'état réel du code et sa documentation. --GarfieldFr
- En fait la documentation générée (par exemple en html) est elle-même une documentation externe qui risque de ne pas être à jour, mais bon...
- Celle généré ne sera peut être pas à jour, mais celle inclus dans les sources le sera. Il est alors simple de regénérer la doc HTML! --GarfieldFr
- Sinon je pense que l'intérêt principal de faire une page par fichier sera de pouvoir discuter de ceux-ci. A partir du moment où on commencera à documenter directement le code source, ces pages pourront d'ailleurs être liées à la documentation générée. (par contre certains fichiers comme wakka.php risquent de devenir vraiment très longs... celui-ci fait déjà plus de 850 lignes, si on le documente bien [compter 5 à 10 lignes par méthode] il fera facilement 2 à 300 lignes supplémentaires !) -- LordFarquaad