Re: Documentation for GNOME API

[philippe truth enit fr]

I already sent a mail about this : has anyone checked the script PERCEPS for 
auto documentation ? Maybe you should as it might provide a good starting point and a big chunk 
of the work is already done.

The script provides ways to output whatever format you want by using templates. It first builts sets of relevant features like :

-classes, members, attributes ...
-functions + args + return value
-macros
-typedefs 

Then it provides a language to loop along items like :

[foreach class][if member] [foreach member] print [name] ...


I had to fix some pbs with the script but it is becoming very usable on a quite large scale software.

I am no good at docbook yet so I am doing an awful job, but I could produce pretty decent output through it
using (as much as I could understand them) the "right" tags like functsynopsis etc.

I could also get the full body to be displayed with cross references to functions calls.

I thought you might be interested so I put a real example below 


Philippe

Here is an example of a template :


<!doctype  Book public"-//Davenport//DTD DocBook V3.0//EN"  > 
<Book>
<bookinfo>
<title> Docs </title>   
</bookinfo>

 <toc></toc>

<chapter id=classes> <title> Classes </title>

[foreach class sort]
	 <sect1  id=[filter id][name][endfilter]> <title>
	 [if templ]template [endif] 
	 [if struct] struct [endif]
	 [else] class [endelse] 
	 [name]  [templ]  </title>

	 [if brief][n][n][brief][endif]
	 [n][n]<sect2> <title> Type </title>
	 <para> [n][if abstract]abstract[endif][else]instantiable[endelse] </para>
	 [if parents][n][n]<sect2> <title> Superclasses </title> 

	 <para> [n][parents] </para>[endif]

	 [if hfile][n][n]<sect2><title> Include file </title>
	 <para>[n][hfile] </para>
	 [endif]

	 [if detail][n][n]<sect3> <title> Detailed description </title> <para> [n][detail][endif]
	 [if dr][n][n]<sect2> <title> Design remarks </title><para> [n][dr][endif]
	 [if bug][n][n]<sect1> <title>Known bugs</title/><para>[n][bug][endif]

	 [if children]
	 <sect3> <title> Children </title> 
	 <para>
	 [n]<listitemizedlist> 
	 [foreach child sort] 
		  [n]<listitem>  [name] 
         [next] 
	 </itemizedlist> [endif]

	 [if author][n][n]<sect2><title> {Programmer} </title>[n][author][endif]
	 [n][n]


	 [if public]
	 <sect2> <title>Public methods </title>

	 <para>
	 [n]<itemizedlist>
	 [foreach public sort]
	 [n]<listitem> <para> [filter attribute kt][type] [mname] [endfilter]
	 [if func]([args])[endif]
	 [if const] const[endif]
	 [if enum]{[args]} [endif] 
	 [if detail]  [detail][endif] 
	 [next public] </itemizedlist>
	 [endif]


	 [endnobreak]


	 </sect2>
	 [next class]

</sect1>
</chapter>
<Chapter id=defines> <title> Gobals </title>
[foreach macro]
<sect1> <title> [name]  [args]  </title>
<para> Defined in : [hfile]
[if detail] <para> [detail] [endif] 
[next]
</chapter>

<Chapter id=functions> <Title> Functions </title>

[foreach hfile]
	 [foreach func]
		[if first]<sect1><title>[hfile]</title>[endif]
		<Funcsynopsis> <FuncPrototype> <funcdef>  [type] <function> <anchor id=[filter id][name][endfilter]> [name]</function> </funcdef>
		[filter margs][args][endfilter] </funcprototype></funcsynopsis>
		[if detail]<programlisting>[filter comm][detail][endfilter]</programlisting>[endif]
  	
		[next]



[next] 
</chapter>
</book>