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

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

Answer 2

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 3

Hi Maybe you should consider using doxygen for documentation as it has a lot more native support for c / c++. if you want to retain the sphinx output of your documentation you can output from doxygen as xml, then using Breathe it will take the xml and give you the same sphinx output you are used to having.

Here is an example of documenting an enum in doxygen format from the breathe website.

//! Our toolset
/*! The various tools we can opt to use to crack this particular nut */
enum Tool
{
    kHammer = 0,          //!< What? It does the job
    kNutCrackers,         //!< Boring
    kNinjaThrowingStars   //!< Stealthy
};

hope this helps.