GNOME Bugzilla – Bug 782162
Support public/private trigraph in glib-mkenums
Last modified: 2017-05-16 10:24:36 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.
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 >*/ MY_FOO_PRIVATE, /*< public >*/ MY_FOO_VALUE_A, MY_FOO_VALUE_B, /*< private >*/ MY_FOO_VALUE_C, MY_FOO_VALUE_D } MyFooValue; The glib-mkenums parser also allows skipping enumeration values, using a slightly different syntax: typedef enum P MY_BAR_PRIVATE, /*< skip >*/ MY_BAR_VALUE_A, MY_BAR_VALUE_B } 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 feasible. 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.
Review of attachment 351057 [details] [review]: This looks OK to me, modulo a few nitpicks about comments. Please push with those changes. ::: gobject/glib-mkenums.in @@ +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.
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.
Attachment 351057 [details] pushed as 9ba17d5 - mkenums: Support public/private trigraph