GNOME Bugzilla – Bug 646094
Get rid of the section.txt file
Last modified: 2018-05-22 13:04:13 UTC
It is cumbersome to manually keep several files up-to-date. We could rather have a convention for assigning symbols to sections (like in the autogenerated sections) file and have markup for the in-source docs to override. E.g.: * * in_section: helpers * Also there could be a commandline option to specify a default section that takes all remaining things.
Better plan: * section-title can be in SECTION comment already * when parsing a SECTION comment, everything in the same file will be by default in that section * we need comment markup to override the section e.g.: " * in-section: xxxx" this needs gtkdoc-mkdb::ScanSourceFile to understand a new tag, which otherwise would appear as verbatim in the sources * if one has "@InSection: xxxx" in a section comment we could patch the main.xml file and insert then xi:include line (would possibly rely on a special comment-pair there, we might also need to rewrite these auto-generated xi:includes everytime as the placements could have been changed, or we have a xi:inlcude for each chapter, that we regenerate). * we need a way to specify subsections (Standart, Private) this could be done in the SECTION comment e.g.: "@HideSymbols: <list-of-symbols-to-hide> * we could allow to have a SUBSECTION:xxx comment block too - but then we list all the symbols here to override the auto-section placement - right now I would rather kill subsections * if we want to avoid the "InSection in symbol docs we could also have e.g.: "@ExtraSymbols: <list-of-symbols-to-include> * documented symbols that are in a file without section comment and do not appear in "@ExtraSymbols", "@HideSymbols" would go to unused.txt * shall we deprecated the unused sub-sections? * can we have both at the same time (for migration) * yes, read section-file first and add/override from inline comments Any oversights? I will start to prototype this.
(In reply to comment #1) > Better plan: > * when parsing a SECTION comment, everything in the same file will be > by default in that section Do you mean it will NOT work like the current auto-generated section (that map header files to sections 1:1 by default) and it will create sections from implementation files instead (unless I put all docs to the headers)? Then I hope the current way will be also possible because it Just Works for a sanely organised public interface (i.e. set of header files) while it still allows to organise the implementation differently.
(In reply to comment #2) > (In reply to comment #1) > > Better plan: > > * when parsing a SECTION comment, everything in the same file will be > > by default in that section > > Do you mean it will NOT work like the current auto-generated section (that map > header files to sections 1:1 by default) and it will create sections from > implementation files instead (unless I put all docs to the headers)? No, it will work the same way. The the "section:" doc blob and the function comments are in the C file anyway. But right the things that are in *one* header file will be put to *one* section, unless otheriwise annotated.
In git head 5fb843d000a97fb1b640816b870fd4eb41a30bbd the heuristics for autogenerated section.txt files are improved. A few things we might want to decide: 1.) for instance decl default scope is private, for normal structs it is public. I'd like to change that so that for class structs the default is private too. This would get rid of the warnings about undocumented parent pointers. Of couse this is hard to make in a backward compat way :/. We could always add an option for the default scopes. 2.) imho people only document classes if there are vmethods in there. would be nice to detect it and put the class var into the right section depending whether its empty or not. 3.) does enyone mind the "in-section:" tags appering verbatim in the docs for old gtk-doc versions?
From bug #751783: it would be good to always generate the master docs.xml file too. Personally, 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 (in-section) match Mallard’s.
-- GitLab Migration Automatic Message -- This bug has been migrated to GNOME's GitLab instance and has been closed from further activity. You can subscribe and participate further through the new bug through this link to our GitLab instance: https://gitlab.gnome.org/GNOME/gtk-doc/issues/13.