GNOME Bugzilla – Bug 546138
don't write empty undeclared/unused/undocumented files
Last modified: 2018-05-22 13:02:15 UTC
it would be nice if gtk-doc didn't write out zero byte files for -undeclared/-unused/-undocumented.txt. this allows you to not have these files in your .gitignore. this means that git-status will alert you when you have undeclared/unused/undocumented symbols. that's quite useful, i think. :) it might also be cool to emit (or not emit) a -warnings.txt file if any WARNING: lines showed up. then git-status could tell you about that too. note: another way of doing this would be to check the zero-byte files into your version control and then you'd see if they changed from being zero bytes. this is a little bit dirty, though (to have zero-byte, machine-generated files in version control). also note: this wouldn't work now anyway because of the statistics at the top of -undocumented.txt.
Doing this unconditionally would break gtkdoc-check that, when enabled, prevents you from doing `make dist' when documentation coverage is not 100%. Allowing the check to simply pass when the checked files are not present would not work because the files may be missing for many reasons. So this unfortunately requires adding another option...
gtkdoc-check should be able to also look for "xml/*.(sg|x)ml" and "html/index.html" and those are not there report that generating the documentation has failed. If they are then it could look into the *.txt files. Its a bit difficult with the -undocumented.txt as this has the completeness summary. I am not saying that this is good, but we can't really break it.
I think gtk-check could look for the *.stamp files to figure if the docs have been built. I'll give this a try. Maybe we can move the status summary from -undocumented.txt into a separate -status.txt. gtkdoc-check could be updated to check for the new one at the same time. Not sure if anyone else relies on the summary in -undocumented.txt. Opinions?
(In reply to comment #3) > Not sure if anyone else relies on the summary in -undocumented.txt. I certainly do. It's the easiest method obtain an overview of the documentation status for inclusion in build reports, etc. In general, the entire motivation for this change seems pretty dubious to me. You have to put the files to .gitignore, what's the problem with that? That's how you handle generated files. And alerting you to undocumented symbols -- why on earth it should be git's job? Furthermore, moving the status summary elsewhere will still break things exactly the same way -- unless there is a *LONG* period during foo-undocumented.txt and foo-status.txt coexist.
We can support both ways for a few years. I never liked that the status in -undocumented.txt. But I agree that the git support is not the way to go. If we want to give developers a way to ensure docs are always good, it'd be better to have something alike to -Werror. It is just so, that these kind of enhancement request make zero sense to stay open, if we can't agree how to go forward :/
-- 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/8.