[glib] mkenums: Support public/private trigraph

[Emmanuele Bassi <ebassi src gnome org>]

commit 9ba17d511e325eec1e0c1c27cb4d37de4f12ac1e
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Thu May 4 15:05:07 2017 +0100

    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.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=782162

 gobject/glib-mkenums.in |   19 +++++++++++++++++++
 1 files changed, 19 insertions(+), 0 deletions(-)
---
diff --git a/gobject/glib-mkenums.in b/gobject/glib-mkenums.in
index 219a166..9316e57 100755
--- a/gobject/glib-mkenums.in
+++ b/gobject/glib-mkenums.in
@@ -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