Developers of Sympa

[Guillaume Rousse <address@concealed>]

Le 13/03/2013 12:22, IKEDA Soji a écrit :
> > > And a comment to POD style by Guillaume: perlpodstyle manpage says
> > > to use 'an "=item" for each interface'.  Almost all CAPN modules
> > > also do it.  Sources in sympa-cleanup branch use "=head2".
I just commited some changes (commits #8945, #8946 and #8947) toward 
this direction.

Using the recommandations from this man page I didn't knew beforehand, I 
dropped usage of =head2 and =head3 tags for structuration, in favor of 
enumerations. To avoid too much imbrications, I didn't use any 
structuration for 'Parameters' and 'Return value' titles. And I used 
italics formatting (I<>) for better function block readability.

Additional style remarks:
- explicit enumeration bullets (ie, '=item * foobar' instead "=item 
foobar") actually harms readability, given lack of indentation in 
following line
- I confused C<> (terminal-style font) vs L<> (link to another man page) 
for classes names

Also, taking inspiration of LWP man page, I switched from a loose 
formulation of parameter type to explicit statement. Ie,:
=item I<message>: the message to format, as a L<Sympa::Message> instance

=item I<openssl>: the path to openssl binary

is now:
=item C<message> => L<Sympa::Message>

The message to format

=item C<openssl> => $path

The path to openssl binary.


Is this new style proposal OK for everyone ?
--
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