inline long description formatting
- From: Stefan Kost <ensonic hora-obscura de>
- To: gtk-doc-list gnome org
- Subject: inline long description formatting
- Date: Thu, 04 Aug 2005 18:42:05 +0200
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
* @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);
* 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.
[Date Prev][Date Next
] [Thread Prev][Thread Next