> What characters does gtk-doc use to introduce a comment?
> I like the idea of having javadoc like comments i.e. /** */
> with some special tags because there are several programms out
> their which make beatyful documentation out of this and it's quite
> a standard solution...
It would look like this:
/**
* 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
* @menu_show_pixels: TRUE if the menu should contain a "Pixel" entry,
* FALSE if not
* @menu_show_percent: TRUE if the menu should contain a "Percent" entry,
* FALSE if not
* @spinbutton_usize: the width of the spinbuttons
* @update_policy: what value should be updated when the user changes
* something
*
* Creates a new #GimpSizeEntry, which can be used to ask the user for
* a length. It allows the size to be specified in pixels or real-life
* units. A #GimpSizeEntry may contain multiple fields which will be
* arranged in a row and share a common unit_menu.
*
* Returns: a pointer to a new gimp_size_entry widget.
*/
GtkWidget*
gimp_size_entry_new (gint number_of_fields,
GUnit unit,
gchar *unit_format,
gboolean menu_show_pixels,
gboolean menu_show_percent,
gboolean show_refval,
gint spinbutton_usize,
GimpSizeEntryUP update_policy)
{
...
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.
Salut, Sven
