Re: [PATCH 5.5.63] Autogenerate API docs, define Perl API

["Benjamin Stuhl" <sho_pi@hotmail.com>]

From: Graham Barr <gbarr@pobox.com>
>To: Gurusamy Sarathy <gsar@ActiveState.com>
>CC: Tim Bunce <Tim.Bunce@ig.co.uk>, Benjamin Stuhl <sho_pi@hotmail.com>,    
>     perl5-porters@perl.org
>Subject: Re: [PATCH 5.5.63] Autogenerate API docs, define Perl API
>Date: Mon, 17 Jan 2000 10:05:42 +0000
>
>On Fri, Jan 14, 2000 at 07:25:52PM -0800, Gurusamy Sarathy wrote:
> > On Fri, 14 Jan 2000 22:22:01 GMT, Tim Bunce wrote:
> > >On Fri, Jan 14, 2000 at 01:22:12PM -0800, Gurusamy Sarathy wrote:
> > >>     /*
> > >>     =proto Am|void|macro|int a|float b|char c
> > >>
> > >>     This macro does stuff.  See L<function>.
> > >>
> > >>     =cut
> > >>     */
> > >
> > >Or even
> > >
> > >	=for perlapi ...
> > >
> > >	...
> > >
> > >	=cut
> > >
> > >to be actual pod rather than pod-like.
> >
> > Works for me.
>
>Do you actually need the =for ?? Why not just the usual =head =item etc.
>Or do you want to translate it differently ?
>
>Also, don't forget the blank line between the /* and the =whatever
>
>Graham.
>

I think that's an argument for merely POD-like syntax, since too many
blank lines in the middle of *.[ch] will severely disrupt the
readability of the Perl source. I am considering

/*
=func flags|ret|name|arg1|...|argN

Documentation in POD format (see L<perlpod>).

=cut
*/

with leaving out return & args for functions already in embed.pl

Is this ok (I'll ask B<before> I submit a patch, this time... :-) )?

-- BKS
______________________________________________________
Get Your Private, Free Email at http://www.hotmail.com

---

Follow-Ups from:

Gurusamy Sarathy <gsar@ActiveState.com>

---

[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index][Thread Index][Top&Search][Original]

---