Discussion :

[Philippe_31]

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

[dmitry_ovsianko]

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.

[Philippe_31]

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

[dmitry_ovsianko]

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 &#40;&#123;type => 'logon', sid => ''&#125;, &#123;kind => 'http'&#125;&#41;;
EO
		label_en => 'Redirects the client to the given URL.',
		label_ru => 'Перенаправление клиента на заданный адрес.',
#		see_also => &#91;qw&#40;draw_form draw_table&#41;&#93;,
		options  => &#91;qw&#40;kind/internal before&#41;&#93;,
	&#125;,
 
...

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

[Philippe_31]

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