Re: Nice stuff

[muppet <scott asofyet org>]

On Tuesday, November 11, 2003, at 10:50 PM, Bruce Alderson wrote:

> I'd like to help with this project, if there's anything that needs
> doing.  I'm an intermediate Perl programmer, an experienced C/C++ dev
> (mostly embedded commercial stuff), and a technical-writer (mostly
> commercial stuff).  I don't mind doing small stuff like writing
> tutorials, or updating documentation ... and can work on bugs and small
> features if it suits.

well, then, i suspect our documentation is easily our weakest suit.

as you may have noticed, the stuff in cvs creates a manpage for just 
about every object, by pulling code descriptions and pod directly from 
the xs source.  as the first stage of documenting the API, we need to 
go through the XS files and document the xsubs which aren't trivial 
---- pretty much anything that says "..." or "list" needs an 
explanation.  (more on how to do this in a moment)

we also need more example programs for the website, 
http://gtk2-perl.sourceforge.net/doc/examples/ .  the stuff should be 
well commented and clean, and do simple but illustrative things.

most of the existing documentation has just been cobbled together over 
time.  it could all use a good editing sweep, with an eye towards 
structure and coherency.


submit your changes as patches for the time being.  it's probably also 
a good idea to announce ahead of time what you're planning to take on 
to avoid duplication of effort.



-=-

for documenting the XS source:  the manpages for Glib::ParseXSDoc and 
Glib::GenPod (both in cvs only) explain a bit, but suffer from the 
"cobbled together" syndrome and may not be complete, so here's a primer.

XS allows embedded pod in both the verbatim C section (from the top of 
the file to the first MODULE line) and the xsub sections (after the 
first MODULE line).

stuff in the verbatim C section is just normal pod, reserved for a 
document that describes the C calling conventions for the library.  at 
the moment, only Glib has anything that needs to be documented in this 
way.

stuff in the xsub sections mostly uses special pod directives we've 
come up with for this doc project.

each MODULE line's PACKAGE statement resets the "current package"; all 
the xsubs and pod found from here until the next PACKAGE line go into 
the doc section for that package.  there is one basic backdoor to allow 
you to put pod into a different package (which is often necessary to 
avoid clobbering existing pages):

 =for object Pod::Name (Object::Name) blurb

Both the (Object::Name) and blurb are optional, as usually the 
Pod::Name is the same as the object name.  
GnomeCanvas/xs/GnomeCanvas.xs shows where you'd use (Object::Name) --- 
basically, the pod for Canvas.pm already create the Gnome2::Canvas 
manpage, so we put the api docs for the Gnome::Canvas object into 
Gnome::Canvas_methods --- the extra "(Gnome::Canvas)" object name 
specification is needed to get the object properties, signals, and 
hierarchy to show up.

Everything from =for object to the next =cut is slurped into this 
object's pod.


To get enums and flags listed in a package, you need to do
  =for enum TypeName
  =cut
or
  =for flags TypeName
  =cut
The =for (enum|flags) directive *must* follow a =cut or it will not be 
seen by the parser (e.g., it cannot occur inside a pod paragraph).  You 
can put pod inside to describe the flags but it's usually not needed.


We use the "=for apidoc" pod directive to document methods.  if the pod 
is "stuck to" the xsub prototype (i.e. no blank lines between =cut and 
the start of the xsub) then that pod will be used to describe that 
method.  otherwise, you need to specify the name of the xsub after the 
apidoc token.  this is most commonly needed for aliases; use the source 
for examples, i'm already out of time to write this completely.

apidoc paragraphs *must* have a =cut -- you can't put three of them in 
the same section.

Pod inside the =for apidoc paragraph is put in the block for that xsub. 
 you can use lists and whatever you want.

In many cases you'll need to "correct" the generated call signature.  
the optional signature directive does this:

  =for signature (something, else) = $object->foo ($bar, $baz)

there's also the optional arg directives:

  =for arg bar (string) something to describe this parameter on one line
  =for arg baz notice how i didn't include the type on this one
  =for arg ... (__hide__) this type is special, and causes the arg not 
to be shown

for more examples, Use the Source, Luke.  if you have any questions, 
email me or come into #gtk-perl on irc.gnome.org.

--
muppet <scott at asofyet dot org>