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 782162 - Support public/private trigraph in glib-mkenums
Support public/private trigraph in glib-mkenums
Product: glib
Classification: Platform
Component: gobject
Other All
: Normal normal
: ---
Assigned To: gtkdev
Depends on:
Reported: 2017-05-04 14:19 UTC by Emmanuele Bassi (:ebassi)
Modified: 2017-05-16 10:24 UTC
See Also:
GNOME target: ---
GNOME version: ---

mkenums: Support public/private trigraph (3.77 KB, patch)
2017-05-04 14:19 UTC, Emmanuele Bassi (:ebassi)
committed Details | Review

Description Emmanuele Bassi (:ebassi) 2017-05-04 14:19:42 UTC
I know that glib-mkenums is being re-written in Python, but maybe we should squeeze this in as well.

This *will* have an impact on the ABI, as symbols that may have been added to the enumeration GType will now cease to exist. Those types were intended to be private in the first place, so I think it's a fair assumption that the impact will be zero in all idiomatic and well-behaved code, but it's a change nonetheless.
Comment 1 Emmanuele Bassi (:ebassi) 2017-05-04 14:19:52 UTC
Created attachment 351057 [details] [review]
mkenums: Support public/private trigraph

It is possible, when using GTK-Doc, to mark sections of an enumeration
type as "private": the values are there, but they are not documented,
and GTK-Doc won't complain about missing symbols:

    typedef enum {
      /*< private >*/

      /*< public >*/

      /*< private >*/
    } MyFooValue;

The glib-mkenums parser also allows skipping enumeration values, using a
slightly different syntax:

    typedef enum P
      MY_BAR_PRIVATE, /*< skip >*/
    } MyBarValue;

The annotation must sit on the same line as the enumeration value.

Both GTK-Doc and glib-mkenum use the same trigraph syntax, but slightly
different keys. This makes combining them slightly redundant, but

All would be well and good, except that glib-mkenum will generate a
warning for lines it does not understand — and that includes the GTK-Doc
annotation trigraph, which, when confronted with the MyFooValue
enumeration above, will result in a warning like:

    glib-mkenums: myfoo.h:2: Failed to parse `  /*< private >*/ '
    glib-mkenums: myfoo.h:5: Failed to parse `  /*< public >*/ '
    glib-mkenums: myfoo.h:9: Failed to parse `  /*< private >*/ '

Of course, we could make glib-mkenum ignore any trigraph comment on a
stand alone line, but it would probably be better to ensure that both
glib-mkenums and gtk-doc behave consistently with each other, and
especially with the maintainer's intent of hiding some values from the
user, and reserving them for internal use.

So we should ensure that glib-mkenums automatically skips all the
enumeration values after a "private" flag has been set, until it reaches
a "public" stanza.
Comment 2 Philip Withnall 2017-05-04 14:43:21 UTC
Review of attachment 351057 [details] [review]:

This looks OK to me, modulo a few nitpicks about comments. Please push with those changes.

::: gobject/
@@ +20,3 @@
 				# guess where to put the underscores.
 my $seenbitshift;		# Have we seen bitshift operators?
+my $seenprivate;                # Have we seen a private option?

How about ‘Have we seen a /*< private >*/ trigraph?’?

@@ +130,3 @@
 	    # ignore preprocessor directives
+        } elsif (m@^\s*
+                   /\*< (([^*]|\*(?!/))*) >\s*\*/

This block could do with a comment briefly explaining what on earth is going on.
Comment 3 Philip Withnall 2017-05-04 14:44:28 UTC
Regarding the API break, I think it’s fine, for the reasons you give. We’re fairly early in the cycle, so any major breakage will quickly become obvious. If it’s a problem, we can always hide this behind a --enable-private option, or something like that.
Comment 4 Emmanuele Bassi (:ebassi) 2017-05-16 10:24:32 UTC
Attachment 351057 [details] pushed as 9ba17d5 - mkenums: Support public/private trigraph