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 751777 - gtk-doc -sections.txt file documentation is a bit confusing
gtk-doc -sections.txt file documentation is a bit confusing
Status: RESOLVED FIXED
Product: gtk-doc
Classification: Platform
Component: general
unspecified
Other Linux
: Normal normal
: 1.25
Assigned To: gtk-doc maintainers
gtk-doc maintainers
Depends on:
Blocks:
 
 
Reported: 2015-07-01 11:44 UTC by Jeremy Whiting
Modified: 2015-09-29 20:07 UTC
See Also:
GNOME target: ---
GNOME version: ---



Description Jeremy Whiting 2015-07-01 11:44:30 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.
Comment 1 Philip Withnall 2015-07-01 11:50:22 UTC
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.
Comment 2 Stefan Sauer (gstreamer, gtkdoc dev) 2015-07-01 19:29:46 UTC
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.
Comment 3 Stefan Sauer (gstreamer, gtkdoc dev) 2015-09-29 20:07:50 UTC
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).