Developers of Sympa

[Guillaume Rousse <address@concealed>]

Le 19/09/2013 17:35, David Verdin a écrit :
>         Documentation
>
>   * We shall stick to the current practice of documenting using POD
Bear in mind than POD is made to document an API. This means than POD is 
unsuitable for private function, and for functions located in an 
executable, where standard comments still make sense.

>   * we will keep on putting sub documentation right above the subs
>     (that's my only disagreement with Damian Conway until now). I think
>     that improves code comprehension.
>

>   * The template for documenting source files is the following:
>
> =head1 FUNCTIONS
>
> =head2 foo($bar)
>
> =head3 parameters
>
> =over
>
> =item * $bar
>
> =back
>
> =head3 Return value
>
> Something
>
> =cut
>
> Using enumeration for function/method names would force us to use
> explicit depth level to each enumerations:
AFAIK, POD parser is able to infer them automatically.

> =head1 FUNCTIONS
>
> =over
>
> =item * foo($bar)
>
> =over 2
>
> =item + parameters
>
> =over 4
>
> =item - $bar
>
> =back
>
> =item + return value
>
> =back

Soji suggested to use enumeration to match perlpodstyle(1). That's 
mostly a cosmetic issue, I think, and I don't really care. Take note 
however than as we're slicing pod with code, there should be only one 
pair or =over/=back tag for a whole API section (class methods, instance 
methods, functions), not one for every subroutine:

=head1 CLASS METHODS

=over

=item Class:method1()

=cut

sub method1 {
}

=item Class:method2()

=cut

sub method2 {
}

=back

=head1 INSTANCE methods

What I do care however is to enforce a consistent formatting for 
documention subroutine prototype:
- for a function: function($param1, $param2, ...)
- for a class method: Class->method($param1, $param2, ...)
- for an instance method: $instance->method($param1, $param2, ...)

Of course, this means we have to get rid of the few ugly routines being 
usable either as a method, either as a function...

Also, while on the documentation topic:

Each package should have a name and a description, preferentially using 
a similar wording a others.

I'm still very sceptic about the random usage of AUTHORS and COPYRIGHT 
POD sections in multiple files. Especially as this leads to duplicated 
informations (we already have copyright information in file headers), 
outdated informations (I think Renater copyright is missing, for 
instance), and discrepancies (Olivier has its name orthographied either 
as Salaun or Salaün, depending of the file). For me this kind of 
information is not file-specific (except a very few case), but global 
for the whole project, and should be centralized in one single place, 
and eventually refered to from file headers and executable documentation.


--
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