Sphinx: Correct way to document an enum?

Question

Looking through the C and C++ domains of Sphinx, it doesn't appear to have native support for documenting enums (and much less anonymous enums). As of now, I use cpp:type:: for the enum type, and then a list of all possible values and their description, but that doesn't seem like an ideal way to deal with it, especially since it makes referencing certain values a pain (either I reference just the type, or add an extra marker in front of the value).

Is there a better way to do this? And how would I go about handling anonymous enums?

Answer 1

A project on Github, spdylay, seems to have an approach. One of the header files at https://github.com/tatsuhiro-t/spdylay/blob/master/lib/includes/spdylay/spdylay.h has code like this:

/**
 * @enum
 * Error codes used in the Spdylay library.
 */
typedef enum {
  /**
   * Invalid argument passed.
   */
  SPDYLAY_ERR_INVALID_ARGUMENT = -501,
  /**
   * Zlib error.
   */
  SPDYLAY_ERR_ZLIB = -502,
} spdylay_error;

There some description of how they're doing it at https://github.com/tatsuhiro-t/spdylay/tree/master/doc, which includes using a API generator called mkapiref.py, available at https://github.com/tatsuhiro-t/spdylay/blob/master/doc/mkapiref.py

The RST it generates for this example is

.. type:: spdylay_error

    Error codes used in the Spdylay library.

    .. macro:: SPDYLAY_ERR_INVALID_ARGUMENT

        (``-501``) 
        Invalid argument passed.
    .. macro:: SPDYLAY_ERR_ZLIB

        (``-502``) 
        Zlib error.

You could take a look and see if it's useful for you.

Answer 2

Sphinx now has support for enums

Here is an example with enum values:

.. enum-class:: partition_affinity_domain

   .. enumerator:: \        
      not_applicable
      numa
      L4_cache
      L3_cache
      L2_cache
      L1_cache
      next_partitionab