GNOME Bugzilla – Bug 638449
gtk-doc master broken on glib docs
Last modified: 2011-11-07 12:53:41 UTC
gtk-doc master breaks e.g. the gspawn docs in glib, which, instead of looking like this: gboolean g_spawn_async (const gchar *working_directory, gchar **argv, gchar **envp, GSpawnFlags flags, GSpawnChildSetupFunc child_setup, gpointer user_data, GPid *child_pid, GError **error); [...] only look like this: #define g_spawn_async_with_pipes Bisecting gtk-doc gives 6689f85421d54949effafb1164f18257927234c1 is the first bad commit commit 6689f85421d54949effafb1164f18257927234c1 Author: Stefan Kost <ensonic@users.sf.net> Date: Mon Sep 20 12:05:13 2010 +0300 scan: track forward decls and thus allow skipping duplicate symbols :100755 100755 5a16f94bec64b7397b9f792764ad173dc73e40d7 4052b8d7b24cad857a574480c049ffe710e16474 M gtkdoc-scan.in
glib$ find . -name "*.h" -exec grep -Hn "g_spawn_async" {} \; ./glib/gspawn.h:79:#define g_spawn_async g_spawn_async_utf8 ./glib/gspawn.h:80:#define g_spawn_async_with_pipes g_spawn_async_with_pipes_utf8 ./glib/gspawn.h:86:gboolean g_spawn_async (const gchar *working_directory, ./glib/gspawn.h:99:gboolean g_spawn_async_with_pipes (const gchar *working_directory, This is as designed. Maybe the defines can be moved below the prototypes? The change fixes issues where the a random / wrong definition was picked up when encountering multiple declarations (in nested ifdefs).
*** Bug 641984 has been marked as a duplicate of this bug. ***
The only alternative I could see is to run the sources through cpp with the right defines being set. Something like CC=gtkdoc-scan make
Any optionion?
*** Bug 647008 has been marked as a duplicate of this bug. ***
Disappointing that this is not moving forward. The documentation cannot be left in its current state. Clearly there was a solution for extracting macro argument names previously, so why is this no longer viable?
(In reply to comment #6) > Disappointing that this is not moving forward. The documentation cannot be left > in its current state. Clearly there was a solution for extracting macro > argument names previously, so why is this no longer viable? Matthew, I suggested to move the #defines down. That should fix it. The problem is not that gtk-doc is not able to extract the macro names anymore. In this case one file contains several definitions of the same symbol. Those are now picked up differently.
Created attachment 186311 [details] [review] Patch for gspawn.h If moving #defines down means placing them after function prototypes in gspawn.h then this patch should fix the problem.
*** Bug 651727 has been marked as a duplicate of this bug. ***
Stefan, should that bug be moved back to glib, and status as NEW?
I don't think that 'keep making random tweaks to the headers' is a valid answer to 'gtk-doc used to handle these fine and now it doesn't anymore'
I agree. But still I feel that the current behavior is better. I happily taking constructive suggestions how to handle multiple definitions. But please understand that developer capacities within gtk-doc are extremely sparse and I feel that the fix attached is the easier solution.
But the patch changes the effective headers on win32, doesn't it ? With the current headers, win32 compilers will see _utf8 calls in the code and _utf8 declarations in the headers. After moving the macros below the declarations, the complier will see _utf8 calls in the code, but no matching declarations in the headers.
I ended up using __GTK_DOC_IGNORE__ to make gtk-doc ignore the renaming macros
This also broke gdk-pixbuf docs (bug 663554), and probably other modules with a similar setup too. I really think this should be fixed in gtk-doc.