inline long description formatting

classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

inline long description formatting

Stefan Sauer-4
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?

Stefan
_______________________________________________
gtk-doc-list mailing list
[hidden email]
http://mail.gnome.org/mailman/listinfo/gtk-doc-list
Reply | Threaded
Open this post in threaded view
|

Re: inline long description formatting

Damon Chaplin
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
[hidden email]
http://mail.gnome.org/mailman/listinfo/gtk-doc-list
Reply | Threaded
Open this post in threaded view
|

Re: inline long description formatting

Matthias Clasen
In reply to this post by Stefan Sauer-4
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
[hidden email]
http://mail.gnome.org/mailman/listinfo/gtk-doc-list