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
approach:
@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...
--
Servus,
Daniel
