Re: Fwd: Kernel-doc^2 (gtkdoc)

[Owen Taylor <otaylor redhat com>]

Actually, gtk-doc goes a lot beyond simply parsing the 
function doc comments. (And in fact, it didn't originally
do that at all!)

Among other things, it:

 - Knows about the GTK+ object system - object heirarchies,
   signals, properties, etc.

 - Parses header files to find out about typedefs,
   
 - Integrates documentation from template files with
   the parsed header files.

   (This one of the distinguishing characteristics of gtk-doc - 
   it doesn't try to put all documentation inline - just
   the parts that make sense.)

There is a fair bit of information the doc/ directory
of gtk-doc/. Trevor Curtis is apparently also doing some
work on doing GDP-style documentation, though I don't
know how far he's gotten with that.


As far as installation, gtk-doc is wonderously easy to install.  There
is a RPM of it in the RH rawhide tree, though it's a bit out of date,
but it's also just a simple:

 ./configure ; make install

out of CVS. The thing about gtk-doc is:

 - It's a tool for GTK+/GNOME programmers to do docs for other
   programmers, so the docs for gtk-doc assume a lot of 
   knowledge about programming.

 - It's a real pain to set it up to document a library. I mean, a
   major pain.  Hard. Involves creating a number of files with magic
   contents, and then knowing more about make than you ever wanted to
   know.

   I've gone out on a limb and made the statement that the reference
   doc makefiles in the HEAD of GTK+ (docs/reference/gtk/Makefile.am, etc)
   are just about perfect. They are also meant to be easy to modify
   without having to change the scary parts.  So, they may be worth
   copying.

   But I wish I knew how we could make it easier to set up.

   More documentation helps, but it there are just too many files to
   juggle, and it shouldn't take 200 lines of Makefile boilerplate.

Once it's been set up. It's not bad to use - you just
either edit the pseudo-sgml files in the tmpl/ directory or
you edit the inline function headers. But the set up is
the killer.

(Perhaps we need to create a gtkdocize script, like libtoolize
and gettextize.)

Regards,
                                        Owen


Telsa Gwynne <hobbit aloss ukuu org uk> writes:

> Various people on this list at times have expressed interest in gtkdoc.
> I have been trying to find info on it. I can't find much. What I have
> is here, because I keep missing people on IRC. And it gets into the
> archives here. And I don't know any more than this, so please don't
> email me Hard Questions!
 
> Apparently the major problem is that it's a complete sod to install.
> If you can't find a nice rpm/deb of it, you're in for pain. Gnome
> apparently has its own little something-doc which is a script by
> Michael Zucchi and is in CVS. That is what the kernel folks used
> as a basis for 'kernel-doc', which is just a script in perl. The
> only feature that it is missing which gtkdoc has is something to 
> do with classes.
> 
> kernel-doc is apparently found in 2.4 (and 2.3 :)) linux kernels
> in /linux/scripts. 
> 
> On the matter of "how to use the thing once it's installed", it's
> the same for kernel-doc and gtk-doc, and so here are the instructions
> for kernel-doc on the basis that it might be a quick-start for
> gtk-doc: 
> 
> From: Alan Cox <alan lxorguk ukuu org uk>
> Subject: Kernel-doc^2
> To: hobbit aloss ukuu org uk
> Date: Mon, 19 Feb 2001 18:03:42 +0000
> 
> 
> Kernel docs on kernel-doc aka much of gtkdoc. Different tools same markup
> so the section on that is relevant and included..
> 
> 
> How to add extractable documentation to your source files
> ---------------------------------------------------------
> 
> The format of the block comment is like this:
> 
> /**
>  * function_name(:)? (- short description)?
> (* @parameterx: (description of parameter x)?)*
> (* a blank line)?
>  * (Description:)? (Description of function)?
>  * (section header: (section description)? )*
> (*)?*/
> 
> The short function description cannot be multiline, but the other
> descriptions can be.
> 
> All descriptive text is further processed, scanning for the following special
> patterns, which are highlighted appropriately.
> 
> 'funcname()' - function
> '$ENVVAR' - environment variable
> '&struct_name' - name of a structure (up to two words including 'struct')
> '@parameter' - name of a parameter
> '%CONST' - name of a constant.
> 
> Take a look around the source tree for examples.
> 
> 
> Tim.
> */ <twaugh redhat com>