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

[Ross McFarland <rwmcfa1 neces com>]

On Wed, 2004-01-28 at 23:45, muppet wrote:

> 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.
>
> ...
>
> this trick would still work for the xsub-less version, of course.

the problem is that if no xsub spec exists for some_perl_sub ParseXSDoc
doesn't pull it out of the pods, it just considers it pod. and doesn't
put it into the xsubs list. and then it gets placed with the normal pods
(not in the methods section) and ignored because of the =for apidoc. so
you never know it's there. 

i've already done exactly this for some of the stuff at work, but they
don't show up. if you look into build/doc.pl they're in there, but as
pods, not xsubs. perhaps some key like =for perl_sub that cases whatever
takes the xsubs out of the pods to take it even thought it doesn't have
an xsubs.

-rm