After an evaluation, GNOME has moved from Bugzilla to GitLab. Learn more about GitLab.
No new issues can be reported in GNOME Bugzilla anymore.
To report an issue in a GNOME project, go to GNOME GitLab.
Do not go to GNOME Gitlab for: Bluefish, Doxygen, GnuCash, GStreamer, java-gnome, LDTP, NetworkManager, Tomboy.
Bug 133500 - Newlines v. Tags in Inline Comment Docs
Newlines v. Tags in Inline Comment Docs
Status: RESOLVED NOTABUG
Product: gtk-doc
Classification: Platform
Component: general
1.1
Other Linux
: Normal normal
: ---
Assigned To: gtk-doc maintainers
gtk-doc maintainers
Depends on:
Blocks:
 
 
Reported: 2004-02-05 13:00 UTC by James Cape
Modified: 2005-08-26 14:01 UTC
See Also:
GNOME target: ---
GNOME version: 2.9/2.10



Description James Cape 2004-02-05 13:00:31 UTC
When tags appear in source comments (e.g. <informalexample>), they are not
respected when there is more than one newline following it. So, while this:

/**
 * some_func:
 * @blah: the blah.
 * 
 * The example:
 * 
 * <informalexample><programlisting>some_func
(my_blah);</programlisting></informalexample>
 **/

works, this:

/**
 * some_other_func:
 * @blah: the other blah.
 * 
 * The example:
 * 
 * <informalexample><programlisting>some_func (my_blah);
 * 
 * some_other_func (&my_blah);</programlisting></informalexample>
 **/

does not, as gtkdoc-mkdb inserts a </para><para> between the two functions.

The proper solution (AFAICT) is to have gtkdoc-mkdb check if there's an
open tag in the comment before it inserts the <para> stuff. This has the
advantage of allowing all sorts of tags into the source comments.
Comment 1 Matthias Clasen 2004-02-05 13:26:56 UTC
I agree that the behaviour could be nicer, but I think I documented


the restrictions. A workaround which I use occasionally is to insert 
comments in the otherwise empty row:




/**


 * some_other_func:


 * @blah: the other blah.


 * 


 * The example:


 * 


 * <informalexample><programlisting>


 *  some_func (my_blah);


 * <!-- -->


 * some_other_func (&my_blah);


 * </programlisting></informalexample>


 **/




If you want to work on improving the behaviour, feel free to propose a 
patch, but beware that there may also be embedded tags inside 
paragraphs, e.g: 




/**


 * some_other_func:


 * @blah: the other blah.


 * 


 * Still need <tag>para</tag>s around this.


 *


 * Although there's a <tag>tag</tag> in there!


 **/


Comment 2 Damon Chaplin 2004-02-15 16:39:32 UTC
One idea would be to check if there is a <para> in the docs anywhere.
If there is, gtk-doc assumes the user is doing all the formatting and
doesn't insert <para>...</para> at all.
Comment 3 Stefan Sauer (gstreamer, gtkdoc dev) 2005-08-24 16:46:39 UTC
just have spaces after the '*' in the empty line, then no </para><para> gets
inserted:

/**
 * some_other_func:
 * @blah: the other blah.
 * 
 * The example:
 * 
 * <informalexample><programlisting>some_func (my_blah);
 *  <- spaces here <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
 * some_other_func (&my_blah);</programlisting></informalexample>
 **/
Comment 4 Geert Stappers 2005-08-26 14:01:10 UTC
The workaround is considered satisfactional,
so this bugreport is closed ( by Stefan Kost )