GNOME Bugzilla – Bug 789087
gint and guint misrepresented as functions
Last modified: 2018-05-22 13:12:54 UTC
The "Basic Types" documentation page lists the `gint` and `guint` symbols as functions instead of types. This seems to have been introduced somewhere between 2.46.2 and 2.48.2 (or perhaps in the gtk-doc versions used), as seen in the hosted docs: https://developer.gnome.org/glib/2.46/glib-Basic-Types.html#gint https://developer.gnome.org/glib/2.48/glib-Basic-Types.html#gint
Looks like a bug in gtk-doc. Reproducible with glib master and gtk-doc 1.26.1 (95a93122a2934e618024f291620edd9c9a3c4e3b).
This was introduces by https://git.gnome.org/browse/glib/commit/glib/gutils.h?id=9834f79279574e2cddc4dcb6149da9bd782dd40d and is not really a gtk-doc bug. gtk-doc would ideally understand this and at least print a better error. I am attaching a patch for glib, let me know if I should push it.
Created attachment 362291 [details] [review] gutils: move defines below prototypes to fix the docs
How on earth are the definitions of the g_bit_*() functions (in gutils.h) affecting the generated documentation for guint and gint (in gtypes.h)?
It is a header file and it clobbers the previous decl. I will add some code to handle this better, the patch is offered to fix the docs now. In any case, most people know that gtk-doc parses headers using a bunch of regexp, challenging the parse is not a good idea :/
(In reply to Stefan Sauer (gstreamer, gtkdoc dev) from comment #5) > It is a header file and it clobbers the previous decl. I will add some code > to handle this better, the patch is offered to fix the docs now. > In any case, most people know that gtk-doc parses headers using a bunch of > regexp, challenging the parse is not a good idea :/ Are you planning to fix this in gtk-doc soon, or will it take a while? I’d rather not push the workaround to GLib unless the gtk-doc fix is going to take a while.
This is the first time it was reported and it is a special case. I need to first figure which regexp to adjust and to carefully test that it has no side effects. Not sure when I can look into it :/
You probably want to add the GLIB_AVAILABLE_* defines into the --ignore-decorators
Fixing this is not going to be easy. 1) We have two declarations for the same symbol (e.g. g_bit_nth_lsf) - one is the macro and one is the actual function. 2) the prototype looks as if: "GLIB_AVAILABLE_IN_ALL" is the return type, "gint" is the function name and "(g_bit_nth_lsf)" are the parameters scan.py:ScanHeader:306:INFO:no decl: #define g_bit_nth_lsf(mask, nth_bit) g_bit_nth_lsf_impl(mask, nth_bit) scan.py:ScanHeader:364:INFO:Macro: "g_bit_nth_lsf" scan.py:ScanHeader:306:INFO:no decl: scan.py:ScanHeader:306:INFO:no decl: GLIB_AVAILABLE_IN_ALL scan.py:ScanHeader:306:INFO:no decl: gint (g_bit_nth_lsf) (gulong mask, scan.py:ScanHeader:552:INFO:Function (2): "gint", Returns: "GLIB_AVAILABLE_IN_ALL" scan.py:ScanHeader:635:INFO:in decl: skip=0 gint nth_bit); Finally, why do we have one impl and both macros that redirect to the impl *and* functions that do this? Backwards compat? Maybe the functions prototypes should be removed from the header?
I’ve filed bug #790015 with some patches to fix various issues with the GLib docs (including adding GLIB_AVAILABLE_* and GLIB_DEPRECATED_* to the --ignore-decorators, thanks for the hint). It improves the docs, but it doesn’t solve the issue here. If I put #ifndef __GTK_DOC_IGNORE__ around the #defines for g_bit_nth_lsf() and friends, I get the following, which perhaps provides a bit more insight into the problem: WARNING:root:Cannnot parse args for function in "g_bit_nth_lsf) (gulong mask, gint nth_bit " WARNING:root:Cannnot parse args for function in "g_bit_storage) (gulong number " /opt/gnome/source/glib/glib/docs.c:1591: warning: Field description for GFloatIEEE754::v_float is not used from source code comment block. ./glib-sections.txt:1867: warning: No declaration found for g_bit_nth_lsf. ./glib-sections.txt:1868: warning: No declaration found for g_bit_nth_msf. ./glib-sections.txt:1869: warning: No declaration found for g_bit_storage.
-- 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/39.