Re: Gtk2-Perl API documentation project

[James Curbo <james teyandei net>]

Pascal Giard wrote:
>  --- Gavin Brown <gavin brown uk com> a écrit :
>
> > > lots and lots of people want it and nobody really thinks it's a bad
> > > idea, it's just a lot of work, and somewhat of a duplication of effort.
> >
> > I have to say I agree with all those points. I think that I while back
> > we discussed the possibility of manipulating gtk-doc data to generate
> > this stuff automatically - any more thoughts on that? Otherwise Ross is
> > setting himself up for a job that'll never be done.
>
>
> i don't think Ross is setting himself for this job, at least, he shouldn't.
> i think it has to be a collective effort, or that it shouldn't happen.
> it's not only my opinion, it is also what i felt in ross' email.
>
> concerning a possible gtk-doc modif, i'm somewhat out of context...
> are you talking about the doc generated from the PODs using gtk-doc ?
> or are the gtk-doc simply the documented C APIs ?
>
> in either way, it'd surely be nice if the most part was automagically generated.

He's talking about using the program. I just glanced at gtk-doc but 
still don't know if it'd be easy or hard to do. I would venture to say 
that a pure POD approach is probably best, with maybe some sort of 
script to generate the pod from the XS. I already wrote a simple IRC bot 
that would parse the XS and get function names from it (C names to Perl 
names, e.g. gtk_button_new -> Gtk2::Button::new), so I don't suppose it 
would be too hard to grab them in a similar manner, Perl-ize them, and 
throw them in a pod. If I was doing it, I'd probably make it generate 
output like so:

Gtk2::Button::new

        C API function: gtk_button_new
        
        (maybe other specific stuff here, perhaps in some sort of
        external file like gtk-doc kind of does; could include an example)

This would make it easy to say at the beginning, "Use the C API listing 
to look up information about the call," since what most people are 
wanting to know is how to map C names to Perl names (explicitly, instead 
of "read Gtk2::api")

What about function arguments though? I don't know much about XS so I 
don't know how they are presented.

> -Pascal

James