GNOME Bugzilla – Bug 751777
gtk-doc -sections.txt file documentation is a bit confusing
Last modified: 2015-09-29 20:07:50 UTC
https://developer.gnome.org/gtk-doc-manual/unstable/metafiles_sections.html.en mentions that the file is similar to xml, but doesn't explicitely say a few things like: <SECTION> should have </SECTION> but <SUBSECTION Foo> shouldn't have a matching </SUBSECTION Foo>. It may also be helpful to add a simple short example for those that learn by example rather than explanatory text.
The page should probably explicitly say that sections.txt is *not* XML. ‘XML-like syntax’ is bound to make people try and close all the tags. Mention that object structs just use their typedef name rather than something like ‘MyObject-struct’ as used for the Docbook IDs; signals aren’t listed; properties aren’t listed; methods and #defines are listed.
I totally agree. Patches welcome. Although ideally, you let gtk-doc generate the -section.txt (especially recommended if its a new project). You can try that using --rebuild-sections in SCAN_OPTION in Makefile.am.
Please consider sending a patch for doc improvements in the future. commit 88bf236077fc5c469aeb8ffc001bbc9e89e56c53 Author: Stefan Sauer <ensonic@users.sf.net> Date: Tue Sep 29 22:04:04 2015 +0200 docs: improve docs for the sections.txt file Explicitly state that this is not xml. Fixes #751777 @Philip, feel free to send a patch to document the details of id generation if you feel like it (in a new ticket).