Re: inline long description formatting

[Damon Chaplin <damon karuna uklinux net>]

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