GNOME Bugzilla – Bug 141899
Use gtk-doc.make
Last modified: 2009-08-15 18:40:50 UTC
Currently, when compiled without --with-html-dir, the docs are installed to $(prefix)/gtk-doc/html, as opposed to $(prefix)/gtk-doc/html/gsf, the "standard" location. This can be easily fixed (and give devhelp support for free) by using the gtk-doc.make file which is pulled in by gnome-autogen.sh.
Created attachment 27388 [details] [review] Patch to use gtk-doc.make
The core of this problem has already been fixed in cvs (thanks JHM and fcrozat) I tried to move to gtk-doc.make a few weeks back which is why it is included in the build. That was why we moved to automake-1.7. Unfortunately it had two major flaws 1) distcheck failed 2) the docs rebuilt every time even if nothing had changed If you can fix these problems I'd be happy to apply the result, but frankly auto* is too much of a time sink for me to bother with it right now.
Created attachment 27400 [details] [review] Updated patch for a nicer docs build all-around. This patch does spew a lot of warnings from the gsf-scan.c compilation, but it that should be fixed in gtk-doc.
Very nice. This worked mostly smoothly I tweaked the remaining warnings. There is still a complaint about the 'No template matches protected in para' which suggests I'm missing something minor somewhere. Additionally any thoughts on the 16% symbol docs coverage (56 symbols documented, 305 not documented) It seems to be including things like the standard type macros. Is there a way to disable that ?
Comment on attachment 27400 [details] [review] Updated patch for a nicer docs build all-around. applied
The "protected" element doesn't exist in the Docbook DTD AFAICT. I think "note" may be a suitable replacement, though. So far as the coverage goes, I only saw a 6 type macros which are being included (from GsfInput and GsfOutput), because they are in a <SUBSECTION StandardImplementation> rather than <SUBSECTION Standard> (which is hidden pending some hackage to gtk-doc to handle that automatically). I'm not sure about the other macros which are showing up. I'm attaching another patch to fix these issues.
Created attachment 27474 [details] [review] Patch to fix type macros and <protected>
Comment on attachment 27474 [details] [review] Patch to fix type macros and <protected> Looks good please commit
I suspect the worst of the coverage issues stem from the plethora of #define offsets for msole and zip files. I don't see alot of benefit in documenting them. People who need them know their names. Is there a way to add a block comment to them to indicate 'these all format specific offsets' ?
There's no way I'm aware of to block-comment these, though a script could probably be used to auto-generate them. They could also be placed in the Standard or Private SUBSECTION to ignore them for now, but they won't show up in the docs then... AFAIK, what's needed is some scriptable "template for SUBSECTION" support in gtk-doc (which could also handle the type macros). Until then, it's got to be done by the module (either manually or by some script). :-(
Lets stick a fork in this one. Thanks for all your help. This is much better.