Fwd: Kernel-doc^2 (gtkdoc)

[Telsa Gwynne <hobbit aloss ukuu org uk>]

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: 

----- Forwarded message from Alan Cox <alan lxorguk ukuu org uk> -----

To: hobbit aloss ukuu org uk
Subject: Kernel-doc^2
From: Alan Cox <alan lxorguk 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>

----- End forwarded message -----