GNOME Bugzilla – Bug 481811
Inline function bodies are confused with declarations
Last modified: 2010-07-13 13:47:06 UTC
Let's assume the following header file: =================================================================== #include <math.h> #define _GWY_STATIC_INLINE static inline _GWY_STATIC_INLINE double gwy_math_fallback_pow10(double x); #undef _GWY_STATIC_INLINE static inline double gwy_math_fallback_pow10(double x) { return pow(10.0, x); } =================================================================== The _GWY_STATIC_INLINE trickery forces gtk-doc to accept the function as it normally refuses to document inline functions. This seems to be a kind of design decision -- line 473 of gtkdoc-scan.in -- and won't be disputed here. Running with --ignore-decorators=_GWY_STATIC_INLINE results in gwy_math_fallback_pow10 picked as expected: <FUNCTION> <NAME>gwy_math_fallback_pow10</NAME> <RETURNS>double </RETURNS> double x </FUNCTION> However, the following rubbish appear in decl.txt too: <FUNCTION> <NAME>pow</NAME> <RETURNS>return </RETURNS> 10.0, x </FUNCTION> I don't understand how return pow(10.0, x); can be recognized as a function with return value `10.0, x'. When templates are used, mktmpl produces the following error: ###Can't parse args for function pow: 10.0, x Without templates, pow() just appears as undocumented.
I belive the design decission is to ignore static functions, as they can hardly be part of public API. So the problem you have is that you want a "static inline" function to be part of the docs?
(In reply to comment #1) > I belive the design decission is to ignore static functions, as they can hardly > be part of public API. Of course they are part of the public API! Why on earth would be they put into the public headers if not for people use them? Why should #define sinc(x) (sin(x)/(x)) be all right, whereas static inline double sinc(double x) { return sin(x)/x; } forbidden? (Note the example is silly, no one would calculate sinc like this, but this is irrelevant for the argument.) Both have their advantages and disadvantages and therefore suitable in different situations (only C++ templates are more or less able to combine the advantages of both), but solve the same problem: to provide a small to-be-inlined piece of code. Well, I strayed from the point. I can force gtk-doc to include them. The primary issue here is that I have to mangle their bodies to prevent strange `declarations' from being found there. And this does *not* depend on whether the functions go into the documentation or not.
So we could try to * expand local defines * fix what ends up in decl.txt I'll add the example to the testcases and see what I can do.
I've added this to tester.h and added the symbol (bug_481811) to the section file /** * bug_481811: * * http://bugzilla.gnome.org/show_bug.cgi?id=554833 **/ #define _TESTER_STATIC_INLINE static inline _TESTER_STATIC_INLINE double bug_481811(double x); #undef _GWY_STATIC_INLINE static inline double bug_481811(double x) { return x*x; } Despite that 'trick', its not beeing added to the decls. No idea how to proceed here.
I'd like to have this fixed too. static inline functions are used the same way as macros in several public header files and should be possible to document the same way ;)
Another case where the parsing fails is in glib/gutils.h g_bit_nth_lsf, g_trash_stack_push eat other symbols. The later eats glib_major_version and co.. WIld guess is that we parse until ');' but ')[\s\n]*{' should also do.
commit 9569daae7fbf4f542050034191cc0798dc53dda5 Author: Stefan Kost <ensonic@users.sf.net> Date: Tue Jul 13 16:44:18 2010 +0300 scan: allow static inline functions in headers. Fixes #481811 Also fix the test case - G_INLINE_FUNC != static inline commit 5fdb82a4b7e71a4801bffc62fc3cb2937b7c7e79 Author: Stefan Kost <ensonic@users.sf.net> Date: Tue Jul 13 16:31:41 2010 +0300 tests: add test case for Bug #481811 No more tricks needed - this now works: /** * bug_481811: * @x: argument * * http://bugzilla.gnome.org/show_bug.cgi?id=481811 **/ static inline double bug_481811(double x) { return g_random_double_range(x,x*x); }