Skip to content
Commit 9ba17d51 authored by Emmanuele Bassi's avatar Emmanuele Bassi 👣
Browse files

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
parent 274f336f
Hide whitespace changes
Inline Side-by-side
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment