luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-07-30 13:53:30 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'aleksm/mkenums-since' into 'master'

Browse Source 
glib-mkenums: allow optional 'since' tag

See merge request GNOME/glib!1492
This commit is contained in:
Philip Withnall
2020-05-14 16:10:33 +00:00
parent 01fbeb601b ec6056e3ab
commit 85f8efae0f
3 changed files with 87 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

63
docs/reference/gobject/glib-mkenums.xml
View File

@@ -172,25 +172,62 @@ in your templates, to improve the reproducibility of the build. (Since: 2.22)
Some C comments are treated specially in the parsed enum definitions,
such comments start out with the trigraph sequence <literal>/*&lt;</literal>
and end with the trigraph sequence <literal>&gt;*/</literal>.
Per enum definition, the options <literal>skip</literal> and <literal>flags</literal> can be specified, to
indicate this enum definition to be skipped, or for it to be treated as
a flags definition, or to specify the common prefix to be stripped from
all values to generate value nicknames, respectively. The <literal>underscore_name</literal>
option can be used to specify the word separation used in the <function>*_get_type()</function>
</para>
<para>The following options can be specified per enum definition:</para>
<variablelist>
<varlistentry>
<term><literal>skip</literal></term>
<listitem><para>
Indicates this enum definition should be skipped.
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>flags</literal></term>
<listitem><para>
Indicates this enum should be treated as a flags definition.
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>underscore_name</literal></term>
<listitem><para>
Specifies the word separation used in the <function>*_get_type()</function>
function. For instance, <literal>/*&lt; underscore_name=gnome_vfs_uri_hide_options &gt;*/</literal>.
</para>
<para>
Per value definition, the options <literal>skip</literal> and <literal>nick</literal> are supported.
The former causes the value to be skipped, and the latter can be used to
specify the otherwise auto-generated nickname.
Examples:
</para>
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>since</literal></term>
<listitem><para>
Specifies the version tag that will be used to substitute the <literal>@enumsince@</literal>
keyword in the template, useful when documenting methods generated from the enums
(e.g. <literal>Since: @enumsince@</literal>). (Since: 2.66)
</para></listitem>
</varlistentry>
</variablelist>
<para>The following options can be specified per value definition:</para>
<variablelist>
<varlistentry>
<term><literal>skip</literal></term>
<listitem><para>
Indicates the value should be skipped.
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>nick</literal></term>
<listitem><para>
Specifies the otherwise auto-generated nickname.
</para></listitem>
</varlistentry>
</variablelist>
<para>Examples:</para>
<informalexample><programlisting>
typedef enum /*&lt; skip &gt;*/
{
PREFIX_FOO
} PrefixThisEnumWillBeSkipped;
typedef enum /*&lt; flags,prefix=PREFIX &gt;*/
typedef enum /*&lt; flags,prefix=PREFIX,since=1.0 &gt;*/
{
PREFIX_THE_ZEROTH_VALUE, /*&lt; skip &gt;*/
PREFIX_THE_FIRST_VALUE,