inline long description formatting

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?


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]