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 _______________________________________________ gtk-doc-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/gtk-doc-list
