IdentifiantMot de passe
Loading...
Mot de passe oublié ?Je m'inscris ! (gratuit)
Navigation

Inscrivez-vous gratuitement
pour pouvoir participer, suivre les réponses en temps réel, voter pour les messages, poser vos propres questions et recevoir la newsletter

Langage Perl Discussion :

[langage] Générateur automatique de documentation d'une appli Perl


Sujet :

Langage Perl

  1. #1
    Candidat au Club
    Inscrit en
    août 2004
    Messages
    3
    Détails du profil
    Informations forums :
    Inscription : août 2004
    Messages : 3
    Points : 2
    Points
    2
    Par défaut [langage] Générateur automatique de documentation d'une appli Perl
    Bonjour à tous,

    Je suis un petit nouveau sur ce site, et j'aurais besoin de votre expérience et vos connaissances en Perl pour m'aider dans ma recherche : J'ai développé depuis plusieurs années une application en Perl sous forme d'une série de commandes proposées aux utilisateurs avec une syntaxe à respecter ; Comme tous le monde le sait, la mise à jour de la documentation est trés fastidieuse et l'on préfère corriger des bugs plutôt que de rédiger de la doc...

    Mon application se compose d'un ensemble de scripts .pl et de 2 ou 3 packages .pm contenant l'ensemble des fonctions et procédures utilisées.

    Connaissez-vous un utilisaire permettant de scanner les scrips et packages (en utilisant des balises dans les entêtes du code) et de produire une documentation sous forme html par exemple. Un utilitaire du même type que Doxygen (réservé aux langages comme c, C++ ou C#).

    J'ai déjà recherché mais en vain ce type d'outils sous Google.
    Merci d'avance pour votre aide et vos propositions

    A+,Philippe

  2. #2
    Membre du Club
    Inscrit en
    août 2004
    Messages
    50
    Détails du profil
    Informations forums :
    Inscription : août 2004
    Messages : 50
    Points : 60
    Points
    60
    Par défaut
    Le système natif de documentation automatique pour Perl est POD (Plain Old Documentation). Par exemple, si votre scipt (ou module) mm.pl contient des lignes comme

    Code : Sélectionner tout - Visualiser dans une fenêtre à part
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    =head1 NAME
     
    Mon::Module
     
    =head1 DESCRIPTION
     
    C'est bien mon module à moi.
     
    Ses avantages sont:
     
    =over
     
    =item un;
     
    =item second;
     
    =item etc...
     
    =back
    alors vous pouvez taper

    pod2html mm.pl > mm.html
    et la doc HTML sera généré. De la même façon, pod2man vous donnera une page man (aide UNIX), pod2latex -- une source LaTeX. Pour en plus savoir plus, consultez la page http://www.perldoc.com/perl5.8.4/pod/perlpod.html.

    Outre ça, il existe beaucoup de modules supplémentaires liés au POD: http://search.cpan.org/search?query=pod&mode=module.

    En même temps, le problème de synchronization persiste: comme vous avez bien remarqué, on préfère toujours modifier le code et pas la doc, soit en HTML séparé, soit en commentares spécieux.

    C'est pourquoi pour mon projet j'ai réalisé un génératueur de documentation qui contrôle le code et avertit des procedures et des paramètres oubliés. Mais il est lié à la structure du projet et donc n'est pas universel. Néanmoins, si ça vous intéresse, je raconterai volontiers comment ça se fait.

  3. #3
    Candidat au Club
    Inscrit en
    août 2004
    Messages
    3
    Détails du profil
    Informations forums :
    Inscription : août 2004
    Messages : 3
    Points : 2
    Points
    2
    Par défaut
    Bonjour,

    Je vous remercie pour cette réponse trés détaillée et aussi rapide.
    Je ne connaissais pas l'exitance de ce module : Il répond exactement à mon besoin.

    Sur votre projet, votre solution de contrôle et de mise à jour de documentation m'interresserai car nos besoins semblent similaires.

    Sans abuser de votre temps, pourriez-vous m'en dire plus ?

    Merci encore,
    Philippe

  4. #4
    Membre du Club
    Inscrit en
    août 2004
    Messages
    50
    Détails du profil
    Informations forums :
    Inscription : août 2004
    Messages : 50
    Points : 60
    Points
    60
    Par défaut
    Je génère l'HTML sans POD, à partitr des tables, pour que mon script sait quels objets ai-je décrit (pardon pour le texte en Russe):

    Code : Sélectionner tout - Visualiser dans une fenêtre à part
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    @subs = (
     
    	{
    		name     => 'redirect',
    		syn      => <<EO,
    	redirect ({type => 'logon', sid => ''}, {kind => 'http'});
    EO
    		label_en => 'Redirects the client to the given URL.',
    		label_ru => '&#1055;&#1077;&#1088;&#1077;&#1085;&#1072;&#1087;&#1088;&#1072;&#1074;&#1083;&#1077;&#1085;&#1080;&#1077; &#1082;&#1083;&#1080;&#1077;&#1085;&#1090;&#1072; &#1085;&#1072; &#1079;&#1072;&#1076;&#1072;&#1085;&#1085;&#1099;&#1081; &#1072;&#1076;&#1088;&#1077;&#1089;.',
    #		see_also => [qw(draw_form draw_table)],
    		options  => [qw(kind/internal before)],
    	},
     
    ...
    Ce n'est pas indispensable, peut-être on peut tirer des noms des têtes POD, c'est à explorer.

    Des procédures. Avec ce petit truc:

    Code : Sélectionner tout - Visualiser dans une fenêtre à part
    1
    2
    3
    4
    5
    6
    sub subs_in ($) {
    	my $package = shift;
    	my @result = ();
    	eval '@result = grep { defined *{$' . $package . '::{$_}}{CODE} } sort keys %' . $package . '::';
    	return @result;
    }
    je retire les noms de toutes les procéures qui appartiennent à un package donné. Donc, je peux calculer la liste de procéures oubliées.

    Des variables. Avec ce petit truc:

    Code : Sélectionner tout - Visualiser dans une fenêtre à part
    1
    2
    3
    4
    use B::Deparse;
    our $deparse = B::Deparse -> new ();	
    eval '$body = $deparse -> coderef2text(\&Zanas::' . $s -> {name} . ')';
    my @soptions = ($body =~ m{\$\$options\{\'(\w+)\'\}});
    je traverse la source (décompilée) de la procédure pour y trouver tous les morceaux comme '$$options{nom_d_option}', d'ou je trouve la liste des options utilisées. Et puis je trouve celles qui ne sont pas documentées.

    Le dernier exige une certaine discipline de codage: chez moi les paramètres cont groupés en tableaux toujours nommés $options, $conf et $preconf.

    Vous pouvez en apprendre plus en jetant un coup d'oeuil sur le module (http://search.cpan.org/~dmow/Zanas-0.9935/). Le génerateur est dans le ficheir Zanas/Docs.pm, il est activé par la commande

    perl -MZanas:ocs -e generate
    Si vous avez de nouvelles questions, n'hésitez pas à demander

  5. #5
    Candidat au Club
    Inscrit en
    août 2004
    Messages
    3
    Détails du profil
    Informations forums :
    Inscription : août 2004
    Messages : 3
    Points : 2
    Points
    2
    Par défaut
    Encore merci,

    Je suis en train de lire la documentation pod et ai déjà commencé quelques tests sur un bout de code.
    Il me faudra quelques temps pour digérer toute l'info que vous m'avez transmise : Je passe donc cette question à résolu.

    Je vous remercie et vos tiendrais au courant de mes investigations .

    Salutations,
    Philippe

+ Répondre à la discussion
Cette discussion est résolue.

Discussions similaires

  1. Réponses: 0
    Dernier message: 25/09/2014, 12h05
  2. [WD14] comment créer automatiquement la documentation d'une application
    Par kitcarson23 dans le forum WinDev
    Réponses: 15
    Dernier message: 02/08/2011, 12h50
  3. Réponses: 4
    Dernier message: 12/04/2007, 21h26
  4. Réponses: 2
    Dernier message: 05/10/2004, 23h43

Partager

Partager
  • Envoyer la discussion sur Viadeo
  • Envoyer la discussion sur Twitter
  • Envoyer la discussion sur Google
  • Envoyer la discussion sur Facebook
  • Envoyer la discussion sur Digg
  • Envoyer la discussion sur Delicious
  • Envoyer la discussion sur MySpace
  • Envoyer la discussion sur Yahoo