Re: Gtk2-Perl API documentation project

[muppet <scott asofyet org>]

On Tuesday, October 21, 2003, at 11:18 PM, Ross McFarland wrote:

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

it's not useless.  a call signature listing would form the basis of a 
real api reference doc system.

here's what i have in mind:


we have a script which parses the xs files for call signatures and 
embedded pod.  the call signatures would come from direct parsing of 
the actual XS code, using the PACKAGE, PREFIX, and ALIAS to make sure 
you get them all, and the typemaps and possibly our maps files to turn 
the C types into perl package types.

this method would extract at the very least a usable list of the 
available functions for an object, which would be like Gtk::reference.

where Gtk::reference fell down was the absence of any useful 
descriptions of the functions, and the fact that the object information 
(like property and signal listings) was all in another file 
(Gtk::objects).

to get around this, we have embedded pod, which is near the function it 
describes, so it can be dumped into that description:

  =for apidoc ret=($foo, $bar, @baz)

  This function returns a list of all the important shizzle for your
  fizzle to wizzle right.  It has lots of side effects and uses lots
  of global variables, and trying to understand it will rob you
  of all your sanity points.  You'd be better off searching for
  cthulu.  you have been warned.

  =cut
  void
  some_crazy_function (Frobnicator * frob, FrobType type)
      PPCODE:
        ...

note the use of some metadata on the =for line of the pod .... we could 
use something like this to explain what the actual return values are 
for the PPCODE function.  CODE functions with OUTLIST could be filled 
out automagically.


we should also build an introspection program which will spit out 
listings of all the object properties and signals, and the object 
hierarchy.

we'd then process the output of our xs parsing magic filter into a 
bunch of pods that we'd install.

a manpage for each object, which lists the type, the lineage, the 
methods, properties, and signals.


basically, we'd implement something very much like gtk-doc, but 
tailored to work with gtk2-perl and to create pod output.


boosh.


this would give us the api listing for all the people who don't grok C, 
and would be a starting point for filling out the descriptions -- which 
is where the duplication comes in, but i think with terse and to the 
point descriptions we can rely on well-named functions to get us by.  
*cough*

ross has a point, that the embedded pod makes the xs code cumbersome; 
this is why i say that we need to generate the listings rather than 
type them in.  the annotations will be needed for the most part only on 
non-trivial functions, so it's less clutter to document only the ones 
that need it.

but i think we can do this, and do it well enough that we could use it 
on any of the add-on projects, too (Gnome2, Gnome2::Canvas, 
Gnome2::Print, etc, etc).


an mockup manpage containing the information we could extract via code 
parsing and introspection:

NAME
        Gtk2::Button -

SYNOPSIS
        Gtk2::Button->new (mnemonic=undef)
        Gtk2::Button->new_from_stock (stock_id)
        $button->pressed
        $button->released
        $button->clicked
        ...

DESCRIPTION
	any text that may be available.  if there's no text, this section 
doesn't appear.

METHODS
        $widget = Gtk2::Button->new (mnemonic=undef)
          - mnemonic: string

        $button->clicked
          here is some descriptive text from a =for apidoc pod.

        $button->set_use_underline (use_underline)
         - use_underline: boolean

        ...

PROPERTIES
        use-underline - boolean - read/write
                blurb text
        ...

SIGNALS
        clicked

        ...



--
muppet <scott at asofyet dot org>