After an evaluation, GNOME has moved from Bugzilla to GitLab. Learn more about GitLab.
No new issues can be reported in GNOME Bugzilla anymore.
To report an issue in a GNOME project, go to GNOME GitLab.
Do not go to GNOME Gitlab for: Bluefish, Doxygen, GnuCash, GStreamer, java-gnome, LDTP, NetworkManager, Tomboy.
Bug 741941 - Last function argument missing in docs (possibly due to macro in code)
Last function argument missing in docs (possibly due to macro in code)
Status: RESOLVED FIXED
Product: gtk-doc
Classification: Platform
Component: general
1.21
Other All
: Normal normal
: 1.22
Assigned To: gtk-doc maintainers
gtk-doc maintainers
Depends on:
Blocks:
 
 
Reported: 2014-12-24 12:59 UTC by Phil Clayton
Modified: 2015-01-07 02:25 UTC
See Also:
GNOME target: ---
GNOME version: ---


Attachments
gtkdoc-scan: function prototypes can have multiple decorators (2.59 KB, patch)
2015-01-06 13:55 UTC, Stefan Sauer (gstreamer, gtkdoc dev)
committed Details | Review

Description Phil Clayton 2014-12-24 12:59:48 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.
Comment 1 Stefan Sauer (gstreamer, gtkdoc dev) 2014-12-24 14:45:20 UTC
Can you add SCAN_OPTIONS=--ignore-decorators='_VTE_GNUC_NONNULL' to your Makefile.am? gtk-doc cannot possible know your own macros.
Comment 2 Phil Clayton 2015-01-02 14:06:30 UTC
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?
Comment 3 Stefan Sauer (gstreamer, gtkdoc dev) 2015-01-02 14:17:25 UTC
(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.
Comment 4 Stefan Sauer (gstreamer, gtkdoc dev) 2015-01-03 14:20:22 UTC
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.
Comment 5 Phil Clayton 2015-01-06 00:59:49 UTC
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.
Comment 6 Stefan Sauer (gstreamer, gtkdoc dev) 2015-01-06 13:55:27 UTC
The following fix has been pushed:
e91d36d gtkdoc-scan: function prototypes can have multiple decorators
Comment 7 Stefan Sauer (gstreamer, gtkdoc dev) 2015-01-06 13:55:31 UTC
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
Comment 8 Stefan Sauer (gstreamer, gtkdoc dev) 2015-01-06 13:57:50 UTC
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?
Comment 9 Phil Clayton 2015-01-07 02:25:27 UTC
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.