GNOME Bugzilla – Bug 133500
Newlines v. Tags in Inline Comment Docs
Last modified: 2005-08-26 14:01:10 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.
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! **/
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.
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> **/
The workaround is considered satisfactional, so this bugreport is closed ( by Stefan Kost )