Re: Gtk2-Perl API documentation project

[Ross McFarland <rwmcfa1 neces com>]

On Tue, 2003-10-21 at 22:09, James Curbo wrote:
> 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.

the method that would be employed as described on the page would be to
put POD comments in the xs files (which is legal, see man perlxs) the
pod would probably just be tagged onto the end of the file, although
interspersed would also be a possibility, 
http://gtk2-perl.sourceforge.net/doc/api/GtkButton.xs
ExtUtils::MakeMaker either has facilities or can be coerced into
creating the man-pages/perldoc from that with out any real magic.
'pod2html GtkButton.xs > GtkButton.html' was used to create the example
html page.

so far as i know no one ever came up with a good way to convert any of
the C doc (in gtk-doc format) to perl. beyond that it wouldn't really
provide for the situations where the perl api has been modified. 

speaking from experience at work, gtk-doc makes nice pages once it's
done but it's a horrible system. the way it is set up is a message and
requires 5 times as much work as should be necessary. i don't have much
faith in there being a good way to auto-generate anything from it that
would be worth the effort. 

it took about 15 mins to do the doc for Gtk2::Button and it is about an
average size widget. if 10 or so people stepped up to do 4 or 5 widgets
then it could be knocked out in a few hours work (each.) do i have faith
that this will happen, not really, but i figured no more effort that it
would take to try to get people to i would try just that. (reverse
psychology)

the possibility exists, although it's not at all trivial, to generate
call signature api listings (no info other than parameters) but
personally i think this is useless, or at the very least not worth the
effort. 

-rm