inline long description formatting

[Stefan Kost <ensonic hora-obscura de>]

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?

Stefan