Re: Feature request: generate documentation from C files

[Simon Josefsson]

Thanks for the feedback so far.  I haven't started looking into this
in more detail yet, but will have more ideas/questions next week.

Tim Janik <address@hidden> writes:

> 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.

Do the BEAST tools handle this?  I.e., will it translate the above
into @verbatim blocks (or whatever would be the appropriate for a
program listing)?

> 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.

I guess this answer my above question somewhat.

I wonder if using SGML within comments is a good thing, I think the
doxygen approach of using a minimal customized markup language look
nicer when reading the source code in emacs.

There is still the problem of converting between the formats, since
neither gtk-doc nor doxygen replace each other.

Thanks,
Simon