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 320010 - section title from mktmpl conflicts with in-line docs
section title from mktmpl conflicts with in-line docs
Status: RESOLVED FIXED
Product: gtk-doc
Classification: Platform
Component: general
1.4
Other Linux
: Normal normal
: ---
Assigned To: gtk-doc maintainers
gtk-doc maintainers
Depends on:
Blocks:
 
 
Reported: 2005-10-27 20:21 UTC by Yeti
Modified: 2006-03-26 14:37 UTC
See Also:
GNOME target: ---
GNOME version: ---



Description Yeti 2005-10-27 20:21:16 UTC
Distribution/Version: FC3/i686

Briefly: gtkdoc-mktmpl always puts a section title to template files.  While it
is possible to override the title in in-line docs, it causes warnings.

Less briefly (assuming normal gtk-doc setup, I'll use my real class names):

1. Create gwyserializable.h, gwyserializable.c source files with some interface
declaration.

2. Add/move section docs for GwySerializable in-line to gwyserializable.c:

/**
 * SECTION:gwyserializable
 * @title: GwySerializable
 * @short_description: Abstract interface for serializable objects.
 *
 * Blah, blah.
 **/

3. In documentation directory, remove tmpl/gwyserializable.sgml to be sure we
everything that's there is automatically generated.

4. Rebuild templates (runs something like: gtkdoc-mktmpl --module=libgwyddion).

5. Look at tmpl/gwyserializable.sgml, it has no field filled, except SECTION
Title that reads:

gwyserializable

6. [Re]build XML (runs something like: gtkdoc-mkdb --module=libgwyddion
--source-dir=../../libgwyddion --sgml-mode --output-format=xml).  It prints

WARNING: Documentation in template file for ./tmpl/gwyserializable:Title being
overridden by inline comments

----------------------

I haven't found any option or procedure that would avoid this warning -- except
for removal of the offending title (that could be done by a custom script in
tmpl-build stage, but...).
Comment 1 Stefan Sauer (gstreamer, gtkdoc dev) 2006-03-21 11:17:01 UTC
This needs more work in the way gtk-doc works. The goal is to optionaly get rid of the intermediate sgml files at all.
Comment 2 Damon Chaplin 2006-03-26 14:37:58 UTC
I've changed it so it doesn't output warnings for overridden titles.