Re: inline long description formatting

[Matthias Clasen <mclasen redhat com>]

On Thu, 2005-08-04 at 18:42 +0200, Stefan Kost wrote:
> hi hi,
> 
> I migrate my classes short/long description from the tmpl-files to the sources 
> .c files at the moment.
> 
> One problem is that I added a <para></para> block automatically and just put the 
> docs into it. While inserting docs all blank lines where replaced by 
> </para><para>. This way one could have plain test inside the doc-comments.
> 
> First problem: source-code examples
> These are wrapped by <programlisting></programlisting>. If there are blank lines 
> inside the sources, we don't want para tags appearing here.
> 
> Second: docbook tags inside the source-comment suck
> As we never said its legal to add docbook comments to the source comments, what 
> about introducing wiki-style markup for the doc-comments. Its much easier to 
> just write
> 
> /**
>   * SECTION::myclass:
>   * @short_description: cool class
>   *
>   * This class has the following features:
>   * - small
>   * - easy to use
>   * - well tested
>   *
>   * The example below shows how to use it in your sources:
>   *  MyClass *my_class=my_class_new(NULL);
>   *
>   *  my_class_do_something(my_class,"Hello");
>   *
>   * Do not forget to free everything after using.
>   */
> 
> A problem that remains it that one can have /* */ comments in examples. Either 
> they need to be written using entities.
> 
> Any comments?

a) markup is allowed in inline comments if you use --sgml-mode

b) docs/gnome.txt contains hints on how to handle the difficulties
with automatic splitting/markup insertion:

This means that you can't use Docbook SGML tags, unless specify the
--sgml-mode
option for gtkdoc-mkdb, which suppresses the escaping of '<', '>' and
'&' and allows Docbook markup in inline comments.

If you are using markup in inline comments, you must be careful to to
not run into problems with the automatic splitting of the comment in
paragraphs at empty lines. A line counts as empty for this purpose, if
it is empty after the removal of the initial ' * ' prefix. Thus you
can work around this problem by adding some trailing whitespace to
lines which should appear as empty, but not end a paragraph. This is 
especially relevant in code examples, which often contain empty lines.


c) yes, docbook markup in inline comments is a bit ugly. At times I have
thought that maybe we should expand the shortcuts which gtk-doc already
offers, by e.g. allowing to write |g_free (foo)| instead of
<literal>g_free (foo)</literal>. Not sure wiki syntax would really be
that helpful, though. If we decide to introduce new abbreviations, it
would probably be a good idea to go over the existing inline docs in
gtk/glib and see what docbook constructs are most commonly used and
worth abbreviating. For example, I have never used lists in inline
comments, so wiki syntax for lists wouldn't seem like a priority to me.

Matthias