Developers of Sympa

[IKEDA Soji <address@concealed>]

Hi developers,

On Mon, 07 Oct 2013 18:20:16 +0200
Guillaume Rousse <address@concealed> wrote:

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

I agree.

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

I thought about that Sympa will be registered to CPAN in future day.
...It is very possible, isn't it?

I don't know why perlpodstyle recommends "=item" (n.b. it is not
always "enumerated" list item).  But, as most CPAN modules follow
this recommendation, why won't Sympa?

It seems not to be good practice that pairs of "=over" and "=back"
cross over subroutine codes.  Nesting level might be broken when
a subroutine (and corresponding POD) was moved.  IMO pairs should
complete in each fragment.

Why I proposed that PODs should be placed just before each
subroutines is, PODs and code had not been in sync: Even when an
interface was added or removed, POD was not always updated
(especially in large package such as List).  Such situation may
occur in the future.

If there are any other solutions to ensure keeping POD up-to-date,
contiguous POD would be put in single place.

<<snip: I might comment in other days to remainder of your post>>

Regards,

--- Soji

-- 
株式会社 コンバージョン  セキュリティ&OSSソリューション部   池田荘児
〒231-0004　神奈川県横浜市中区元浜町3-21-2 ヘリオス関内ビル7F
e-mail address@concealed  TEL 045-640-3550
http://www.conversion.co.jp/