GNOME Bugzilla – Bug 741941
Last function argument missing in docs (possibly due to macro in code)
Last modified: 2015-01-07 02:25:27 UTC
In the VTE function reference, the last argument is missing in the quoted function signature for most functions - see e.g. https://developer.gnome.org/vte/0.38/VteTerminal.html Similarly for the current unstable. The affected functions appear to be those whose prototype is followed by _VTE_GNUC_NONNULL(...) - see e.g. https://git.gnome.org/browse/vte/tree/src/vteterminal.h#n131 The current thinking is that this macro is confusing gtk-doc.
Can you add SCAN_OPTIONS=--ignore-decorators='_VTE_GNUC_NONNULL' to your Makefile.am? gtk-doc cannot possible know your own macros.
Thanks. The macro takes an argument so I found that I needed to use --ignore-decorators='_VTE_GNUC_NONNULL\s*\([^)]*\)|G_GNUC_MALLOC' which also ignores G_GNUC_MALLOC. This fixed most functions but those with more than one macro are still a problem, for example: void vte_terminal_set_color_foreground(VteTerminal *terminal, const GdkRGBA *foreground) _VTE_GNUC_NONNULL(1) _VTE_GNUC_NONNULL(2); Is gtk-doc expected to match multiple instances of the regular expression specified in ignore-decorators?
(In reply to comment #2) > Thanks. The macro takes an argument so I found that I needed to use > --ignore-decorators='_VTE_GNUC_NONNULL\s*\([^)]*\)|G_GNUC_MALLOC' > which also ignores G_GNUC_MALLOC. > > This fixed most functions but those with more than one macro are still a > problem, for example: > > void vte_terminal_set_color_foreground(VteTerminal *terminal, > const GdkRGBA *foreground) > _VTE_GNUC_NONNULL(1) _VTE_GNUC_NONNULL(2); > > Is gtk-doc expected to match multiple instances of the regular expression > specified in ignore-decorators? Probably not, it could make sense repeatedly apply the ignore-decorators expression until it does not match anything. I'll give this a try later today and also add a test for this.
Phil, can you change the _VTE_GNUC_NONNULL macro to take a list of positions instead? See e.g. nonnull in https://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html __attribute__((nonnull (1, 2))); This would also be in sync with G_GNUC_PRINTF.
It looks straightforward to define something like #define _VTE_GNUC_NONNULL(...) __attribute__((__nonnull__(__VA_ARGS__))) and change the function annotations but it is up to the VTE developers whether they accept such a patch. I'm not sure that would entirely solve the problem, however. The following function would still have two macros and the last argument is still lost when using --ignore-decorators='_VTE_GNUC_NONNULL\s*\([^)]*\)|G_GNUC_MALLOC' char *vte_terminal_get_text(VteTerminal *terminal, VteSelectionFunc is_selected, gpointer user_data, GArray *attributes) _VTE_GNUC_NONNULL(1) G_GNUC_MALLOC; Changing the order of the macros did not help either.
The following fix has been pushed: e91d36d gtkdoc-scan: function prototypes can have multiple decorators
Created attachment 293926 [details] [review] gtkdoc-scan: function prototypes can have multiple decorators Instead of allowing none or one, allow any number of decorator matches at the end of prototypes. Fixes #741941
Was easier than I though when I first checked it. Having a #define G_GNUC_NONNULL(...) __attribute__((__nonnull__(__VA_ARGS__))) in glib would be nice, do you want to propose that?
Great - that fixes it for --ignore-decorators='_VTE_GNUC_NONNULL\s*\([^)]*\)' While testing, I found that specifying alternatives e.g. --ignore-decorators='_VTE_GNUC_NONNULL\s*\([^)]*\)|_VTE_BLAH' requires ...|${IGNORE_DECORATORS}\s*|... changing to ...|(${IGNORE_DECORATORS})\s*|... because the trailing space should be allowed to follow any of the alternatives, not just the last. I was about to propose G_GNUC_NONNULL but a search found some lengthy discussion about it where a decision was made that it shouldn't be added because the introspection annotations should be used to provide such information: https://bugzilla.gnome.org/show_bug.cgi?id=113075#c46 Therefore, VTE should probably fall into line with the GLib guidelines in README.rationale anyway so I've raised https://bugzilla.gnome.org/show_bug.cgi?id=742501 Still it's good that gtk-doc is more robust.