Documentation interne de sous-routine

Version imprimable

07/11/2016, 11h48
dca_marshall

Documentation interne de sous-routine
Bonjour,

Je vais essayer de faire cours :

Dans un gros programmes Perl, j'exécute des règles de manipulation.
Ces règles (des sous-routines) se compte par millier.
Ces règles sont classées dans des Package différents.
En fonction de paramétrage (des fichiers JSON), les modules/package embarquants les règles souhaitées, sont chargés dynamiquement par le programme lui même.
Cette méthode me permet une vraie souplesse, même si ça met un peut de temps à démarrer.

Toutefois, la documentation me fait défaut (tien c'est bizarre, je suis le seul...)
Cette documentation n'a pas pour objectif de décrire l'arbre de développement, mais plutôt un recueil des actions de chaque règle et des attributs d'objets manipulés, à destination d'utilisateurs.

J'ai tenté plusieurs solutions y compris doxygen, mais sans réel succès.
Le POD ne me convient pas, je le trouve polluant en nombre de ligne, pour finalement très peut d'intérêt et pas du tout sexy.

J'ai donc commencé à mettre la documentation relative à chaque règle (sous-routine), dans des variables locales à chacune de ces fonctions.
Le but est de garder la documentation très proche de la fonction, donc à l'intérieur (comme un header en somme).
Les variables on toujours le même nom, pour simplifié la maintenance, ceci m'évite de mettre le nom de la fonction dans la variable.
J'ai bien entendu tenté aussi de mettre toute la documentation dans un Hash, avec les noms de fonctions, mais j'ai trouvé cela très lourd, lors des maintenances et changement de nom de fonction (les noms sont plus proche d'un rôle fonctionnel, que d'une appellation technique).
Si j'oubliais de changer le nom d'une clé de Hash, la documentation devenais fausse (c'est pire que tout :roll:)
Le texte de documentation, "quoté" (q{ }), est lui même en Markdown.
Pour documenter une fonction, j'ai besoin de trois ou quatre variables représentant :
- La synthèse
- Le descriptif détaillé
- Les attributs manipulés
- Les messages associés
- Le complément d'information
Bien entendu je me charge de faire les liens avec les différentes références.

Je cherche donc un module, à positionner dans une seule étape, qui me permettrait de balayer tous les pointeurs de fonctions chargées et avec Padwalker (encore merci à cmcmc pour ça), accéder à leurs variables "my" (peek_my).
Puis, pour terminer, un module qui reprendrai le texte Markdown (je pense à Text::Markdown), pour le mettre dans des portions de HTML (ou XHTML) pour faire une vraie documentation sexy.
La version PDF de la documentation me paraît aussi une bonne solution.
Dans ce cas faire alors du HTML to PDF ou Mardown to PDF ?!

Pour information, j'ai bien trouvé un endroit ou positionner PadWalker avant l'exécution d'une fonction, mais je ne passe pas toujours dans ce code et surtout il peut être appelé des millions de fois. Ce qui n'est pas très performant...

Je vous remercie d'avance de vos idées ou solutions.

Note : J'utilise aussi Moose, pour des centaines de catégories d'objets et 3 à 10 niveaux d'héritage. Mais paradoxalement, j'ai moins de problèmes, car Moose à des modules d'accès aux propriétés et attributs des objets.
Ainsi je récupère bien la documentation de chaque attribut.
Chaque propriété d'objet est documenté, mais pas encore en Mardown (mais ça vient).

Désolé d'être verbeux, mais il me semblais nécessaire d'être précis.
C'est peut être devant mon nez, ou alors je suis neuneu, mais je ne trouve rien... 8O

Encore merci d'avance :P

DCA
07/11/2016, 18h59
Lolo78

Citation:

Envoyé par dca_marshall

Le POD ne me convient pas, je le trouve polluant en nombre de ligne, pour finalement très peut d'intérêt et pas du tout sexy.

Vraiment? Pourquoi donc? Je ne vois pas vraiment l'avantage du markdown par rapport au POD si le but est finalement d'en faire du HTML ou du PDF. Et le POD s'intègre tout de même mieux à du code Perl, non?

Citation:

Envoyé par dca_marshall

Je cherche donc un module, à positionner dans une seule étape, qui me permettrait de balayer tous les pointeurs de fonctions chargées et avec Padwalker (encore merci à cmcmc pour ça), accéder à leurs variables "my" (peek_my).
Puis, pour terminer, un module qui reprendrai le texte Markdown (je pense à Text::Markdown), pour le mettre dans des portions de HTML (ou XHTML) pour faire une vraie documentation sexy.
La version PDF de la documentation me paraît aussi une bonne solution.
Dans ce cas faire alors du HTML to PDF ou Mardown to PDF ?!

Si tu tiens au markdown, pourquoi pas, mais je verrais plutôt du texte en syntaxe markdown, mais placé entre des balises POD de début et de fin pour le mettre en commentaire (ce qui permet de ne pas gêner la compilation du code), et un script Perl qui récupère la doc entre les balises POD et retraite le markdown pour fabriquer du HTML.
07/11/2016, 19h50
dca_marshall
Bonjour Lolo78,

Merci pour ta réponse.

Malheureusement je ne reviendrai pas sur le POD.
J'en ai fait un peu dans mes début en Perl, mais obliger des sauts de lignes pour faire des ruptures, me parais trop lourd et ancestral. Ce ne me semble pas confort de scroller une dizaine d'écran avant d'atteindre un code de qq lignes.
La doc c'est bien, mais je veux pas qu'elle devienne une contrainte.

Il y a déjà de la documentation dans ce programme, mais elle n'est pas en POD.
C'est du commentaire, parser par Doxygen et j'aime bien cette approche de balise dans le texte.

De plus, je rappelles que tous les Package ne sont pas chargés et donc, pour faire la doc POD, je devrais savoir quelles sont les package qui ont été chargés, par le biais des noms de fonctions.
J'ai bien déjà des stats la dessus, mais je ne sais dans quel Package elles se trouvent.

A noter aussi :
- que des fonctions portant le même nom, peuvent être dans plusieurs packages, mais ne font pas la même chose, donc une DOC différentes bien sur.
- enfin, je met à jour à la volée, certaines variables de mon meta-language dans la documentations (dans la partie extraction par Doxygen).
Le Mardown me semblais pas mal du tout, pour formater un peu le texte basiquement, mais surtout m'intéresse pour les minis tableaux, titre, liens, etc.

La finalité en HTML, n'est pas encore certaine.
En fait je regarde aussi la possibilité de mettre en oeuvre un Mojocilious pour cette documentation.

Il y a longtemps je faisais de l'assembler, et on avait toujours un registre quelque part, qui permettait le chaînage de descente dans les autres registres (l'ancêtre du HashRef)
Je recherche un peu la même chose en fait...

Donc je recherche toujours un module possible, pour atteindre ces pointeurs de functions en fin de programme.

...
07/11/2016, 20h32
djibril

Bonsoir,

Enfin un sujet sur de la documentation des codes Perl :aie: ! C'est déjà une très bonne idée d'avoir la volonté de commenter ces codes :ccool:.
En ce qui concerne la méthode, je ne suis pas un très grand expert, néanmoins, je trouve que POD est un bon langage de rédaction. Il faut l'utiliser avec une certaine rigueur et une méthode que l'on se fixe. Distinguer le documentation utilisateur de la documentation technique, écrire la documentation utilisateur dans les fichiers sources et en fin de programme, écrire la documentation technique dans des .pod externe avec les bonnes directives (=for, =end...). Mais comme ta documentation est surtout dédiée à l'utilisateur, du POD en fin de fichier source me semble plutôt correct.
Tu peux même mettre des commentaires particulier qui pourront te servir de débogage avec l'utilisation du module Smart::Comment.
Avec ton POD, la vérification de la documentation, la conversion en HTML, LaTeX, nroff, markdown... ou autres devient simple. Et il existe des modules, programmes te permettant de t'imposer une rigueur comme commenter toutes les procédures. Bref, le POD n'est pas plus beau ou plus moche que le Markdown, le LaTeX... Il suffit de s'y plonger sérieusement.

Ce n'est que mon avis, hein :aie: !!!
07/11/2016, 20h35
djibril

Citation:

Envoyé par dca_marshall

J'en ai fait un peu dans mes début en Perl, mais obliger des sauts de lignes pour faire des ruptures, me parais trop lourd et ancestral.

Bah le Markdown... :aie: !
08/11/2016, 20h02
dca_marshall

Bonjour,

Merci pour ta réponse djibril.
Je vais regarder de plus près le module Smart::Comment, qui me semble plutôt sympa et voir comment l'exploiter.

Mais à la limite, peut importe le format du texte de documentation Mardown ou n'importe quoi d'autre (en fait j'ai pas d'avis définitif la dessus).
Il se peut même que je pousse directement cette doc dans une DB, pour un framework (peut être mojolicious ou CodeIgniter).

J'ai même déjà fait des tests avec des shortcode maison dans du Wordpress et des tableau DataTables.
Ca avait une super gueule ! mais quelles usine à gaz... Donc j'ai vite abandonné :roll:.

Pour le POD j'aimerai bien être convaincu avec du concret.
Donc si tu as des liens qui démontre la qualité du résultat final ( PDF et/ou HTML), je suis preneur et près à revoir mon jugement.
Mais jusque là, rien vu d'époustouflant !

A noter que cette doc fera des centaines de milliers de lignes et doit être parfaitement organisée pour les différents utilisateurs (des Clients et des Opérateurs).
Tout ne devra pas être visible pour les uns et les autres.

Au risque de me répéter, je recherche juste un moyen d'obtenir un pointeur sur des fonctions de package chargés, sans connaitre les noms de package et fonctions :D

Je continu à chercher aussi de mon coté.
A suivre...
08/11/2016, 21h11
djibril

Quelque soit l'outil que tu utiliseras, il te faudra une bonne organisation et il n'y a que toi pour gérer cela, difficile de t'aider.
Je sais juste qu'avec POD, il existe : pod2html, pod2pdf, pod2markdown, pod2latex, pod2text. Et je n'ai pas creusé tous les modules du CPAN.
C'est toi qui décide de ce que tu rédiges, des titres... certaines personnes utilisent même POD pour rédiger des tutoriels comme ils utiliseraient Markdown. Il existe des modules pour le parser également, donc tu peux ensuite le convertir en ce que tu veux.
L'avantage, c'est qu'il est issu de Perl donc contient une panoplie de modules et est intégrable dans le code source ou non Perl.

Voilà, je n'ai pas plus d'avis. De toute façon, quelque soit ta solution, il y aura du boulot d'organisation, de développement peut-être de parsing de la documentation... et surtout un boulot de maintenance.