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

[Gurusamy Sarathy <gsar@ActiveState.com>]

On Mon, 17 Jan 2000 06:38:46 PST, "Benjamin Stuhl" wrote:
>From: Graham Barr <gbarr@pobox.com>
>>Do you actually need the =for ?? Why not just the usual =head =item etc.
>>Or do you want to translate it differently ?

A formatter that understands what the flags mean may emit a more
readable prototype, describe the other attributes of the function, &c.

>>Also, don't forget the blank line between the /* and the =whatever

Perl itself is ok with the starting and stopping sequences appearing
in the middle of a paragraph, but Pod::Parser appears to have trouble
with it.  This is valid Perl, but Pod::Parser sees no pod here:

    # start comment
    =head1 one

    This is pod.

    =cut
    # end comment
    print "hi\n";

I think this ought to be parsed as pod by Pod::Parser.

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

I think you should go ahead and do the above; we can fix it up to
be in a valid Pod::Parser syntax later, if that works out.

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

You should also sync to the latest repository state before making the
patch.  See ftp://ftp.linux.activestate.com/pub/staff/gsar/APC/00README 

Thanks!


Sarathy
gsar@ActiveState.com

---

References to:

"Benjamin Stuhl" <sho_pi@hotmail.com>

---

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

---