Re: Gtk2 apidoc TODO's, and a apidoc general todo

["Ross McFarland" <rwmcfa1 neces com>]

muppet said:
> On Wednesday, January 28, 2004, at 02:45 PM, Ross McFarland wrote:
>
> > as for the general todo. we need to come up with a way to add methods
> > to the
> > list of an object's methods when there's no xsubs for them.
>
> depends on whether the pod shall stay in the pm file with the method,
> or can be kept in the xs file with the other xsubs.
>
> for the latter (all doc in the xs file), we could just have a "=for
> apidoc symname" block in the style of all the others.

i coded up this in about 30 seconds, but the problem was that it doesn't
behave like all of the magic code that turns xsubs into doc'd methods so you
end up having to hand write the pod to look like the stuff apidoc auto gens.
which isn't ideal for several reasons, mainly being taht if we change the way
the pod is done you'd have to go back. that left me with the line of thinking
taht we'd need a more complex system that let us give the info the nomral
xsubs have.

> for the former, we'd need a special heading so that "=for include
> !podselect headingname" would work.  perhaps, "=head1 METHODS" and
> "=for include !podselect METHODS"?  this would make the doc more likely
> to stay up-to-date, but would make ordering a little more difficult.

probably have the same issues as above.

> Glib::ParseXSDoc and Glib::GenPod are going to need a whole lot of
> documenting by the time this is over; they've grown rather intricate.

i've tried to document all of the magic that i've been putting in lately as i
put it in.

it would be kinda evil, but it's actually looking like it might be the best
solution at this point but something like this might work.

#if 0
/* never complied */
=for apidoc
Returns a list of magic beans.
=cut
void
some_perl_method (GObject * its, int params)
    PPCODE:

#endif

since it's i the #if 0 it would never get compiled, but ParseXSDoc pick it up,
and provided that the package->can the method name GenPod will put it into the
apidoc, even though the xsub wasn't used and it's a perl method. the only
downside is that you'd have to keep the fake xsub in sync with the perl sub,
but at this point it's looking like it might be the best route since you'll
have to do something magic anyway.

-rm