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.
This sounds like this bug: http://bugzilla.gnome.org/show_bug.cgi?id=133500 > 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. I think we have to allow DocBook in source code comments. I think it is already used in places. I'm not sure adding wiki-style markup is worth the effort. Damon _______________________________________________ gtk-doc-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/gtk-doc-list
