GNOME Bugzilla – Bug 594224
Please fix manual about inlined SECTION comments (and show warnings when invalid)
Last modified: 2009-09-29 14:12:29 UTC
I was following the manual to move liboobs from using static section descriptions to inlined ones. And I spent a few hours trying to find out why they were not taken into account. My mistake was that I though the SECTION tag was here to set the name of the section, while it is used to identify an already-named section. So I was using 'SECTION:OobsUser' when I should have passed 'SECTION:oobs-user', and set the title instead. The problem is, the manual does not explain that: http://library.gnome.org/devel/gtk-doc-manual/stable/documenting_sections.html.en I think it should just say what the SECTION tag should match, that would save much time for developers! Beyond that, I can't understand why the scanner did not print any warning about an unknown section being commented. That would have made me understand the problem immediately. Generally, failing silently makes a software very hard to set up, when it could be very easy...
commit 314b61f6ca5d3b23f1bd15ea21816b202b224857 Author: Stefan Kost <ensonic@users.sf.net> Date: Tue Sep 29 17:07:41 2009 +0300 gtkdoc-mkdb: add a warning if section name is not used in -section.txt This check can only be used in we don't autogenenrate the sections.txt file. commit d8c1ba2fe23b901512a3383c0ac87c52be470701 Author: Stefan Kost <ensonic@users.sf.net> Date: Tue Sep 29 16:35:25 2009 +0300 docs: clarify link between SECTION:tag and FILE in -section.txt. Fixes #594224 Also fix the spelling of the sections.txt file.