GNOME Bugzilla – Bug 751783
Creating master xml document documentation is a bit lacking
Last modified: 2015-07-02 23:00:19 UTC
The documentation at https://developer.gnome.org/gtk-doc-manual/unstable/metafiles_master.html.en mentions how to create the document and the header but doesn't do into much detail about how the rest of the document should/could be written. For example: Nothing is mentioned about how to add auto generated documentation for objects like this: <xi:include href="xml/foo-version.xml"/> <xi:include href="xml/foo-component.xml"/>
See also: bug #743182 and bug #742580 for ways to (slightly) simplify the top-level XML file.
Jeremy, since gtkdoc-1.23 gtkdoc add generated optional parts in commented form, so that you just have to un-comment them if you like to have them. Besides for all regular sections, gtkdoc-check will notify you if there is a xml file that is generated but not included from the doc. In the long-run we could add an option to gtkdoc-mkdb to *always* regenerate the master-doc. In order to get there, bug #743182 surely helps, but we also need a way to customize how the doc is structures (e.g. add a "@in_section: foo" tag so that one can group sections into chapters.
(In reply to Stefan Sauer (gstreamer, gtkdoc dev) from comment #2) > (e.g. add a "@in_section: foo" tag so that one can group sections into chapters. I would be very much in favour of something like this — I’m a big fan of Mallard’s declarative, auto-linking approach, and I think it would work well for gtk-doc too. Bonus points if the syntax and semantics for it match Mallard’s. :-D
Just to make sure we don't side track too much
Let me know if I missed something: commit dc713a5336936c3eb57f5d45abc3023cc6e9de96 Author: Stefan Sauer <ensonic@users.sf.net> Date: Wed Jul 1 22:13:42 2015 +0200 help: improve docs about editing the master xml document Fixes #751783
(In reply to Stefan Sauer (gstreamer, gtkdoc dev) from comment #4) > Just to make sure we don't side track too much Thanks! I copied my comments about Mallard to bug #646094.