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?

score 6 · Answer 1 · edited May 18 '17 at 10:31

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.

Thanks for the suggestion Alex -- I needed an example of this too! I've taken the liberty of editing the Sphinx markup it generates for the example into your answer. — Blair, May 18 '17 at 10:32

score 1 · Accepted Answer · answered Apr 16 '20 at 23:36

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

answered Apr 16 '20 at 23:36

rscohn2

899
7
10

Unfortunately this is too late for me, but I’m very glad that this has been addressed for future users. – JustSid Apr 16 '20 at 23:53

score 0 · Answer 3 · edited Mar 25 '19 at 18:04

0

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.

edited Mar 25 '19 at 18:04

albert

8,285
3
19
32

answered Jul 24 '13 at 05:06

Zanven

144
6

2

I prefer Sphinx over Doxygen because it's easier to customize, and the way Breathe works isn't really compatible with the way our documentation is written (besides, looking at the output, they seem to have a similar problem with presenting enums).Breathe and Doxygen aren't viable options for us, sorry. – JustSid Jul 24 '13 at 06:06

Sphinx: Correct way to document an enum?

3 Answers3