Developers of Sympa

[Guillaume Rousse <address@concealed>]

Le 19/11/2012 17:33, David Verdin a écrit :
> Hi guillaume,
>
> POD is OK, but on my opinion, documentation at the head of the functions
> is a very valuable information. We often need this to make sure what a
> function is supposed to do...
> On my opinion, we should place such POD comments at the head of each
> function.
That's basically a choice between direct documentation reading confort, 
and formatted documentation structuration.

If you're keeping documentation interleaved with code, it's indeed 
easier to read while editing the code. However, you're forced to split 
other parts of your documentation floating, as your final rendering will 
be file-order-dependant.

For instance:

=head1 NAME

=head1 DESCRIPTION

blablabla

=cut

use strict;
use somethingelse;

=HEAD1 CLASS METHODS

=head2 new

blablabla

=cut

sub new {
}

=HEAD1 INSTANCE METHODS

=head2 do_something

blablabla

=cut

sub do_something {
}

etc...

If you keep documentation separated, you have less formatting 
constraints, it's easier to sport inconsistencies between functions 
descriptions, and often make small functions more readable, as you can 
keep the full code in one single windows:

use strict;
use somethingelse;

sub new {
}

sub do_something {
}

1
__END__

=head1 NAME

=head1 DESCRIPTION

=HEAD1 CLASS METHODS

=head2 new

=HEAD1 INSTANCE METHODS

=head2 do_something

I have a personal preference for the second format, but I'll happily 
revert to the first one if there is a no consensus here :)

--
Guillaume Rousse
INRIA, Direction des systèmes d'information
Domaine de Voluceau
Rocquencourt - BP 105
78153 Le Chesnay
Tel: 01 39 63 58 31

Attachment: smime.p7s
Description: Signature cryptographique S/MIME