Sfinge: modo corretto per documentare un enum?

Question

Guardando attraverso lo C and C++ domains di Sphinx, non sembra avere supporto nativo per documentare enumerazioni (e molto meno enumerazioni anonime). A partire da ora, uso cpp:type:: per il tipo enum, e quindi un elenco di tutti i possibili valori e la loro descrizione, ma non mi sembra un modo ideale per affrontarlo, soprattutto perché rende il riferimento a certi valori un dolore (o Faccio riferimento solo al tipo o aggiungo un indicatore extra davanti al valore).

C'è un modo migliore per farlo? E come andrei a gestire le enumerazioni anonime?

Answer 1

Ciao Forse dovresti prendere in considerazione l'utilizzo di doxygen per la documentazione poiché ha molto più supporto nativo per c/C++. se vuoi conservare l'output della sfinge della tua documentazione, puoi fare un output da doxygen come xml, quindi usando Breathe prenderà l'xml e ti darà lo stesso output di sfinge che sei abituato ad avere.

Ecco un esempio di documentazione di un enum in formato doxygen dal sito web del respiro.

//! 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 
}; 

spero che questo aiuti.

Answer 2

Un progetto su Github, spdylay, sembra avere un approccio. Uno dei file di intestazione a https://github.com/tatsuhiro-t/spdylay/blob/master/lib/includes/spdylay/spdylay.h ha codice come questo:

/** 
* @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; 

C'è qualche descrizione di come lo stanno facendo a https://github.com/tatsuhiro-t/spdylay/tree/master/doc, che include l'utilizzo di un generatore di API chiamata mkapiref.py, disponibile presso https://github.com/tatsuhiro-t/spdylay/blob/master/doc/mkapiref.py

La RST che genera per questo esempio è

.. 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. 

si potrebbe dare un'occhiata e vedere se siamo noi per te