Re: Gtk2-Perl API documentation project

[Ross McFarland <rwmcfa1 neces com>]

On Wed, 2003-10-22 at 00:52, muppet wrote:
>    =for apidoc ret=($foo, $bar, @baz)
>
>    This function returns a list of all the important shizzle for your
>    fizzle to wizzle right.  It has lots of side effects and uses lots
>    of global variables, and trying to understand it will rob you
>    of all your sanity points.  You'd be better off searching for
>    cthulu.  you have been warned.
>
>    =cut
>    void
>    some_crazy_function (Frobnicator * frob, FrobType type)
>        PPCODE:
>       ...

we can/could parse the xsubpp generated c file with an algorithm
something like:

while( <CFILE> )
{
        # XS(XS_Gtk2__Button_new_from_stock)
        $fname = $1 if /^XS(\(.*\))$/;

        # ...Usage:Gtk2::Button::new_from_stock(class, stock_id).
        if /Usage:/
        {
                $sig = $_;
                $sig =~ s/.*(\(.*\)).*/$1/;
                $funcs{$fname} = $sig;
        }
}

we could find the perl names of functions by looking at newXS calls in
the BOOT section. if the first parameter is class then Gtk2:XXX->$fname
($sig), otherwise $class_obj->$fname ($sig). this would even work for
ALIAS and PPCODE functions even resolving all of their names correctly.

the only questions remaining are how you come up with the class object
($class_obj,) maybe they could always be the same thing $obj or
something. the other question is how you associate descriptions with a
function. then something like the =for apidoc above could work. parsing
the xs file building up the list of for apidoc's. something like:

=for apidoc fname_here

foo bar blah blah blah

=cut

the only thing this doesn't deal with are return values, but they could
likely be fitted into this scheme somehow.

-rm