luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-01-12 15:36:17 +01:00
Code Issues Packages Projects Releases Wiki Activity

mkenums: Support public/private trigraph

Browse Source 
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.

https://bugzilla.gnome.org/show_bug.cgi?id=782162
This commit is contained in:
Emmanuele Bassi 2017-05-04 15:05:07 +01:00
parent 274f336f6a
commit 9ba17d511e
1 changed files with 19 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
gobject/glib-mkenums.in
View File

@ -19,6 +19,7 @@ my $option_lowercase_name; # DEPRECATED. A lower case name to use as part
# uses abnormal capitalization and we can not
# guess where to put the underscores.
my $seenbitshift; # Have we seen bitshift operators?
my $seenprivate; # Have we seen a private option?
my $enum_prefix; # Prefix for this enumeration
my $enumname; # Name for this enumeration
my $enumshort; # $enumname without prefix
@ -115,6 +116,8 @@ sub parse_entries {
$seenbitshift = 1;
}
next if $seenprivate;
if (defined $options) {
my %options = parse_trigraph($options);
if (!defined $options{skip}) {
@ -125,6 +128,21 @@ sub parse_entries {
}
} elsif (m@^\s*\#@) {
# ignore preprocessor directives
} elsif (m@^\s*
/\*< (([^*]|\*(?!/))*) >\s*\*/
\s*$
@x) {
my ($options) = ($1);
if (defined $options) {
my %options = parse_trigraph($options);
if (defined $options{private}) {
$seenprivate = 1;
}
elsif (defined $options{public}) {
$seenprivate = 0;
}
}
} else {
print STDERR "$0: $file_name:$.: Failed to parse `$_'\n";
}
@ -353,6 +371,7 @@ while (<>) {
}
$seenbitshift = 0;
$seenprivate = 0;
@entries = ();
# Now parse the entries