On  2 Feb, Sven Neumann wrote:

> /**
>  * gimp_size_entry_new:
>  * @number_of_fields: the number of entries
>  * @unit: the default unit
>  * @unit_format: a pointer to a format string describing the unit

> The good thing is that gtk-doc checks that the documentation and the 
> source are in sync and it creates DocBook SGML that can be used to 
> create nicely linked HTML. In the example above all gimp-specific
> types and enums (GUnit, GimpSizeEntryUP, GimpSizeEntry) would be
> linked to their declaration. But I guess you have worked with the glib
> and gtk+ reference manuals before and know how the output looks like.

 Hm, yes, but the gtk+ manual is not quite what I had in mind.
 I thought of really in-source-documentation and looking at your example
 code I think you had the same in mind. 
 But I would like to use a standard not a new solution, therefor your
 examplecode doesn't match my thoughts. Defining the
 documentation of the parameters directly by giving every one unified
 metatag is very restricting. Javadoc like sourcecode has a better

 @memo      short documentation                    
 @doc       long documentation                     
 @return    doc of return value of a function  
 @param     doc of parameter of a function         
 @exception doc for exepction thrown by a function
 @see       cross reference                       
 @author    author                                
 @version   version                               

 There are at least a few dozen programms which can extract this and
 export them to at least that number of formats. Have a look at doc++,
 a very cute program to generate documentation...


Reply via email to