GNOME Bugzilla – Bug 690941
gtkdoc-fixxref: Add an --ignore-list option
Last modified: 2018-05-22 13:07:37 UTC
Created attachment 232449 [details] [review] gtkdoc-fixxref: Add an --ignore-list option Some functions have types from external libraries without gtk-doc documentation and thus impossible to cross-reference. With this patch gtk-doc offers an option to ignore those types and not warn about them when encountered. A step in the quest to get Cogl's gtk-doc generation warning free with: --ignore-list=HWND,MSG,SDL_Event,XEvent,Display Bike-shedding on the option name and details that I have missed are more than welcomed.
IMO something like this would be quite useful. By `something like this' I namely mean that in my opinion it should take the list of symbols from a file, one symbol per line. A file is much easier to maintain than a list in already messy Makefile, it can be even updated semi-automatically in some cases. It would introduce a de facto dependence on the ignore-file which would not be represented in Makefile. But that is no different from the dependence on Makefile. Another thing to consider might be regular expressions (with implied \A...\Z) instead of strings. You could use SDL_.* to match any SDL symbol then. This would also make easier to write gwy_rand_foo() functions in the docs (with literal `foo' placeholder in the function name) instead of something like <function>gwy_rand_foo<!-- -->()</function> functions in order to get a sane markup without crosslink complaints as I could just ignore gwy_[a-z_]+_foo.
+1 I would not mind having both a --ignore-list and --ignore-file. I also agree on each entry being a regexp. Ideally gtkdoc-fixxref would collect the missing references (it does already to not warn twice) and print a sorted list to file, which can be edited and copied to the suppression file (unconditionally or if another flag is given?). Any takers for a patch?
-- 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/25.