Re: Feature request: generate documentation from C files

[Tim Janik]

On Sat, 25 Oct 2003, Alper Ersoy wrote:

> Hi!
>
> Simon Josefsson:
> > One question: do you have any markup language to use within the
> > GTK-DOC comments, to create, e.g., lists, links, indentation?  Can you
> > use texinfo commands?
>
> I have to admit that I'm not very familiar with GTK-DOC tools.  In
> fact, I have never used them yet, so I don't really know if it has
> such functionalities.  Also regarding Texinfo commands, since the
> Texinfo command prefix clashes with the param type, you can't use them
> directly.  GTK-DOC seems to be a very minimal markup format :\

it's not. gtk-doc does allow for sgml markup, e.g.:

/**
 * gtk_dialog_run:
 * @dialog: a #GtkDialog
 *
 * Blocks in a recursive main loop until the @dialog either emits the
 * response signal, or is destroyed.
[...]
 * Typical usage of this function might be:
 * <informalexample><programlisting>
 *   gint result = gtk_dialog_run (GTK_DIALOG (dialog));
 *   switch (result)
 *     {
 *       case GTK_RESPONSE_ACCEPT:
 *          do_application_specific_something (<!-- -->);
 *          break;
 *       default:
 *          do_nothing_since_dialog_was_cancelled (<!-- -->);
 *          break;
 *     }
 *   gtk_widget_destroy (dialog);
 * </programlisting></informalexample>
 *
 * Return value: response ID
 **/

it just "also" features a special set of markup short hands, i.e. #,
@, () and %, for type names, variables, functions and constants.

> IIRC our scanner in BEAST/BSE allows one to use @*, but that's special
> cased and last time we checked Tim Janik was uncomfortable with
> further breaking the compatibility with the original tools.  However,
> he's very approachable, and you may try checking with him too before
> making your final decision.  So I'm adding him to the CC list.

our scanner is actually very limited, as it only supports the markup short
hands from gtk and nothing more. this has to be fixed though, since we:
a) need more markup facilities in the existing docs and
b) need to be able to also document structures/classes/objects besides
   just functions which are currently supported.

since all other docs in beast are based on texinfo, a future extension
of our markup scanner will most probably get support for texinfo markup,
and with that leave the route of gtk-doc compatibility.

> > so I might spend time on writing a doxygen2gtkdoc.
>
> I suppose this will be a lossy conversion.

probably not since gtk-doc does allow for sgml markup.

>
> Bye,
>
> --
> Alper Ersoy
>

---
ciaoTJ