GNOME Bugzilla – Bug 602026
Warn if non-existing function gets referenced
Last modified: 2009-12-02 11:03:25 UTC
I realized this while looking at bug 601874. gtk-doc knows that this function doesn't exist in documentation anywhere so it'd be nice if it would tell the developers. This is especially nice as a reminder to fix docs when you're changing API in unstable versions.
gtk-doc does not know for sure, becasue links could be external links. I could only add warnings if gtkdoc-fixxref is removing links. Ideally this would trac those warnings, so that I don't warn multiple times.
Yeah, you'd need to emit warnings after gtkdoc-fixxref has run. But then, a warning is fine, because it means that either your fixxref setup is broken or that the function does not exist.
Its not a easy as I thought. So I definitely need to cacth duplicates to just warn for the first time and maybe have a supression for trivialities. html/tester-GtkdocTester.html:1: warning: no link for: void, void. html/tester-GtkdocTester.html:1: warning: no link for: unsigned-, unsigned . html/tester-GtkdocTester.html:1: warning: no link for: void, void. html/tester-GtkdocTester.html:1: warning: no link for: signed-, signed . html/tester-GtkdocTester.html:1: warning: no link for: void, void. html/tester-GtkdocTester.html:1: warning: no link for: intpid, intpid. html/tester-GtkdocTester.html:1: warning: no link for: int, int. html/tester-GtkdocTester.html:1: warning: no link for: int, int. html/tester-GtkdocTester.html:1: warning: no link for: bug, bug. html/tester-GtkdocTester.html:1: warning: no link for: void, void. html/tester-GtkdocTester.html:1: warning: no link for: int, int. html/tester-GtkdocTester.html:1: warning: no link for: void, void. html/tester-GtkdocTester.html:1: warning: no link for: unsigned-long-, unsigned long . html/tester-GtkdocTester.html:1: warning: no link for: void, void. html/tester-GtkdocTester.html:1: warning: no link for: char, char. html/tester-GtkdocTester.html:1: warning: no link for: char, char. html/tester-GtkdocTester.html:1: warning: no link for: char, char. html/tester-GtkdocTester.html:1: warning: no link for: int, int. html/tester-GtkdocTester.html:1: warning: no link for: void, void. html/tester-GtkdocTester.html:1: warning: no link for: double, double. html/tester-GtkdocTester.html:1: warning: no link for: int, int. html/tester-GtkdocTester.html:1: warning: no link for: int, int. html/tester-GtkdocTester.html:1: warning: no link for: int, int. html/tester-GtkdocTester.html:1: warning: no link for: long, long. html/tester-GtkdocTester.html:1: warning: no link for: void, void. html/tester-GtkdocTester.html:1: warning: no link for: unsigned-, unsigned . html/tester-GtkdocTester.html:1: warning: no link for: void, void. html/tester-GtkdocTester.html:1: warning: no link for: signed-, signed . html/tester-GtkdocTester.html:1: warning: no link for: void, void. html/tester-GtkdocTester.html:1: warning: no link for: intpid, intpid. html/tester-GtkdocTester.html:1: warning: no link for: int, int. html/tester-GtkdocTester.html:1: warning: no link for: int, int. html/tester-GtkdocTester.html:1: warning: no link for: bug, bug. html/tester-GtkdocTester.html:1: warning: no link for: void, void. html/tester-GtkdocTester.html:1: warning: no link for: int, int. html/tester-GtkdocTester.html:1: warning: no link for: void, void. html/tester-GtkdocTester.html:1: warning: no link for: unsigned-long-, unsigned long . html/tester-GtkdocTester.html:1: warning: no link for: void, void. html/tester-GtkdocTester.html:1: warning: no link for: char, char. html/tester-GtkdocTester.html:1: warning: no link for: char, char. html/tester-GtkdocTester.html:1: warning: no link for: NULL:CAPS, <code class="literal">NULL</code>. html/tester-GtkdocTester.html:1: warning: no link for: char, char. html/tester-GtkdocTester.html:1: warning: no link for: int, int. html/tester-GtkdocTester.html:1: warning: no link for: void, void. html/tester-GtkdocTester.html:1: warning: no link for: double, double. html/tester-GtkdocTester.html:1: warning: no link for: int, int. html/tester-GtkdocTester.html:1: warning: no link for: int, int. html/tester-GtkdocTester.html:1: warning: no link for: int, int
commit 2415121e8f5f7f6e3ce325c8bdad47287b206b9b Author: Stefan Kost <ensonic@users.sf.net> Date: Wed Nov 25 12:26:07 2009 +0200 fixxref: add warning about broken links. Fixes #602026 Produce less links (e.g. for symbols with spaces). Add a log warning for first time use of non xrefable links (no line number :/). I'll call this fixed fro now. There will be some followup commits to tune it a bit. Unfortunately I found no way to get a linenumber when doing multiline regexp matches - any idea?
After recent commits I am now down to 14 warnings on gstreamer core that are not so easy to fix not to hide. I declare it decent for now :) Would be cool to get feedback of using this on gtk/glib ...
I get awful lots of them with Gwyddion libs. They are of several kinds: 1. libc types and functions mentioned in the docs for various reason: from #FILE and #int16_t to strcmp(), many of these -- of course they are not crosslinkable but explicit DocBook markup gets ugly quickly in such cases 2. mentions of functions in FooClass struct written as destroy(), also quite a lot -- I'd like these to be actually links but I cannot link to individual members 3. examples with hypotetic class names: gwy_foo_duplicate() -- of course these are not crosslinkable but explicit DocBook markup gets ugly quickly in such cases 4. punctuation picked up after types: #GtkListStore-like; yes, this is hard, anyway I'd like to be able to write plurals of types without resorting to #GQuark<!-- -->s or greengrocer's apostrophes #GQuark's 5. enum values of foreign modules; apparently %GTK_SELECTION_BROWSE is not crosslinkable unless you are Gtk+ and of course the real ones. So it is useful but I'm not sure how useful it will be always-on.
I agree that it is much better to have printf() silently produce the right markup for a function than to emit tons of warnings for missing links.
Actually, after the latest changes, I have only very few left for gstreamer. I am not against making such warnings conditional, but then gtk-doc would need some generic way to request this (something like in gcc for -Wall -Werror -Wthis-and-that -Wno-this-and-that plus a decent default set). Yeti, some comments on what you mention. 1.) yes, those are nasty and I see no easy way to skip/hide/ignore them. 2.) just write #FooClass.destroy() 3.) if you want to reference multiple variants you can write gwy_*_duplicate() (of course no link). 4.) Hmm, did not got that one. 5.) This should actualy work (if you built the gtk+ docs with new gtk-doc) What I could do is to limmit the warnings to the projects own prefix. That is for gtk I would only produce warnings for symbols starting with gtk_|GTK_|Gtk. Getting a full list would be nice as well, but would then need some option. I could also disable this for a 1.12 and reenable in git only for now. I still like to have it in priciple, as I found quite a lot of crap in gstreamer docs already :)
(In reply to comment #6) > 4. punctuation picked up after types: #GtkListStore-like; yes, this is hard, > anyway I'd like to be able to write plurals of types without resorting to > #GQuark<!-- -->s or greengrocer's apostrophes #GQuark's > Oh, this is a more general problem (I guess this should be a separate bug?): It would be awesome if there was a way for gtk-doc to detect that when I write "You can put multiple #GtkWidgets in a #GtkContainer" it would know that I meant to link to "#GtkWidget" and just used the plural without me having to resort to <!-- --> magic. Not sure how easy that would be to get right though. Probably just ignoring an 's' at the end would catch 90% of those cases.
(In reply to comment #9) > (In reply to comment #6) > > 4. punctuation picked up after types: #GtkListStore-like; yes, this is hard, > > anyway I'd like to be able to write plurals of types without resorting to > > #GQuark<!-- -->s or greengrocer's apostrophes #GQuark's > > > Oh, this is a more general problem (I guess this should be a separate bug?): > It would be awesome if there was a way for gtk-doc to detect that when I write > "You can put multiple #GtkWidgets in a #GtkContainer" it would know that I > meant to link to "#GtkWidget" and just used the plural without me having to > resort to <!-- --> magic. > Not sure how easy that would be to get right though. Probably just ignoring an > 's' at the end would catch 90% of those cases. Actually, this is what I just committed. I run the current git of gtk-doc on more libs and I have not many false hits left.
(In reply to comment #8) > 1.) yes, those are nasty and I see no easy way to skip/hide/ignore them. For libc, which is the where most of these unlinkable symbols come from, you can take the list of functions e.g. from ISO C99 annex B, maybe plus what's standardized for unistd.h and a handful of glibc names, and get 95%+ coverage. Types are bit harder to extract unless you find a source that lists them nicely. > 2.) just write #FooClass.destroy() I see, thanks. > 3.) if you want to reference multiple variants you can write gwy_*_duplicate() > (of course no link). That would spoil the readability of concrete examples, imagine replacing all instances of maman and bar with * (and another *?) in something like http://library.gnome.org/devel/gobject/stable/chapter-gobject.html I'm afraid this one is not solvable because the symbols look like they belong to the library in every aspect -- except that they do not exist. On the other hand only docs demonstrating the use of abstract interfaces on examples are affected, and that probably isn't that many. > 5.) This should actualy work (if you built the gtk+ docs with new gtk-doc) I see. I have gtk+ docs from my distro built with stable gtk-doc (which is terribly obsolete BTW). > What I could do is to limmit the warnings to the projects own prefix. That is > for gtk I would only produce warnings for symbols starting with gtk_|GTK_|Gtk. Maybe, maybe not. It found quite a few of broken links to foreign libraries -- mainly plurals of types but also others. These would go unnoticed.
Created attachment 148482 [details] C99 libc functions
If we could generate a gtkdoc book that proxies man-pages of some sections that we don't need to avoid the c runtime links. E.g. in gstreamer I had fork() and poll() which are not in your list. I will try to catch types (e.g. xmlNodePtr) to get rid of those false hits next.
At some point I was experimenting with generating man:printf links for such functions, which yelp handles nowadays, I think.
(In reply to comment #14) > At some point I was experimenting with generating man:printf links for such > functions, which yelp handles nowadays, I think. Generating such links would be easy. Would this invoke yelp from devhelp? Also do you happen to remember how you decided to go for a man: link? Did you checked for each symbol if mandb would have a page for it?
(In reply to comment #8) > 2.) just write #FooClass.destroy() It does not really cut it. I tried it with a struct that contains function pointers -- before reailizing that gtkdoc does not know they are pointers so the ()s after member names must confuse it. But I really the want ()s in the text, it makes the description much clearer. I also tried it with an interface struct and still get warnings for references such as #GwySerializableInterface.request(). It simply linkifies the interface name #GwySerializableInterface and prints a warning about request().
#GObjectClass.dispose() does not work either, but maybe gobject docs would have to be rebuilt with HEAD gtkdoc to get crosslinks to members in foreign modules. Under what conditions it is supposed to work?
(In reply to comment #17) > #GObjectClass.dispose() does not work either, but maybe gobject docs would have > to be rebuilt with HEAD gtkdoc to get crosslinks to members in foreign modules. > > Under what conditions it is supposed to work? Its seems to be flawed. I'll have a potential fix. Will push it hopefully tomorrow.
(In reply to comment #17) > #GObjectClass.dispose() does not work either, but maybe gobject docs would have > to be rebuilt with HEAD gtkdoc to get crosslinks to members in foreign modules. > > Under what conditions it is supposed to work? I checked and there is actually an example in the tests: You had to write: #GtkdocObjectClass.test or in your case #FooClass.destroy I made a fix in git so that you can also write #FooClass.destroy()
Current git version is much better. For glib (core) I get 72 warnings. I can already see how to hide more (class="literal"), which would bring it down to 30 and those seem to be real.
(In reply to comment #20) > Current git version is much better. I can confirm that, I get only real and unavoidable[*] warnings now. Good work. [*] Well, avoidable by using explicit mark-up for things that do not really exist instead of gtk-doc shorthands, though I don't like this much.