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

[muppet <scott asofyet org>]

On Wednesday, January 28, 2004, at 09:19 PM, Ross McFarland wrote:

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

that's already the case for normal pod.  the maintenance issue is the 
only one that i really worry about, but since we have =for args and 
=for signature i don't think that;s such a big deal.

  =for apidoc some_perl_sub
  =for signature (thing1, thing2) = $object->frobnicate ($foo, $bar)
  =for arg foo (Fluffle) a snuffle
  =for arg bar (Pluffle) a kerpuffle
  Something that does something to something for some reason or another.
  =cut

that's really no different than what we're doing in dozens of places 
already.  we provide all the type information and the signature, and 
GenPod formats it for us.


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

unfortunately, i did not adequately document the original magic as i 
wrote it, because it changed too quickly.

> 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.
>
> since it's i the #if 0 it would never get compiled, but ParseXSDoc 
> pick it up,

given that the way i showed above and your example of using a shadow 
xsub that doesn't actually get compiled are simply two ways to provide 
metadata, i would choose the no-xsub-involved one for two reasons: one, 
it doesn't require the synchronization of three things (doc, xsub, and 
sub), and does not involve a sneaky code hack just for doc.  the format 
we use for the apidoc pod already lets us override everything that the 
xsub parser can provide, and in many situations (especially the list 
processors and returners that are easier to write in perl than in xs) 
we would have to do that anyway.  simply put, i do not want to 
duplicate the information, which is what using the shadow xsub does.

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

this trick would still work for the xsub-less version, of course.


--
"it's hard to be eventful when you have this much style."
   - me, rationalizing yet another night of sitting at home.