GNOME Bugzilla – Bug 320010
section title from mktmpl conflicts with in-line docs
Last modified: 2006-03-26 14:37:58 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...).
This needs more work in the way gtk-doc works. The goal is to optionaly get rid of the intermediate sgml files at all.
I've changed it so it doesn't output warnings for overridden titles.