Documenting new enum/flags members

Platform
,
1

Hi,

What is the correct way to document the “Since” attribute of a new enum or flag value?

The few existing examples I found seem to not work. For example the Gio.ApplicationFlags:

in the docs all members are individually shown as “Available since: 2.28”, despite being sometimes specified otherwise in the code ( G_APPLICATION_DEFAULT_FLAGS is available since 2.74 for example)

(side note: it’s not an issue with gi-docgen, as members don’t even have a version attribute set in “Gio-2.0.gir”)

2

You can use a docblock for the newly added members, like:

/**
 * FooBar:
 * @FOO_BAR_ALPHA: Alpha
 * @FOO_BAR_BRAVO: Bravo
 *
 * FooBar enumeration.
 *
 * Since: 1.2
 */
typedef enum {
  FOO_BAR_ALPHA,
  FOO_BAR_BRAVO,
  FOO_BAR_CHARLIE
} FooBar;

/**
 * FOO_BAR_CHARLIE:
 *
 * Charlie.
 *
 * Since: 1.8
 */

The docblock can be anywhere, including inside the enumeration itself. You don’t even need the separate @ENUM items:

/**
 * FooBar:
 *
 * FooBar enumeration.
 *
 * Since: 1.2
 */
typedef enum {
 /**
  * FOO_BAR_ALPHA:
  *
  * Alpha.
  */
  FOO_BAR_ALPHA,
 /**
  * FOO_BAR_BRAVO:
  *
  * Bravo.
  */
  FOO_BAR_BRAVO,
 /**
  * FOO_BAR_CHARLIE:
  *
  * Charlie.
  *
  * Since: 1.8
  */
  FOO_BAR_CHARLIE
} FooBar;

The documentation is associated to symbols, and that documentation can be placed anywhere as long as the symbol is declared in scope.

3

OK, thanks!

That’s a bit annoying that those existing inlined “Since” annotation are ignored, as splitting the doc as proposed is a big effort…

4

Those are not annotations: it’s just freeform text. You cannot put paragraphs in the @ENUM blocks either, and the Since: X.Y tag has to be on a line of its own to be detected, you can’t do:

@FOO_BAR_ALPHA: Alpha
  Since: 1.4
@FOO_BAR_BRAVO: Bravo
  Since: 1.6

The @ENUM_VALUE notation is a gtkdoc-ism, and gtk-doc has no idea about versioning of fields or enumeration members; the notation itself is adapted from function arguments, and those cannot be versioned.

1 Like
5

got it, thanks for the clarification!