Сфинкс: Правильный способ документировать перечисление?
Глядя через Домены C и C ++ Sphinx, похоже, не имеет встроенной поддержки документирования перечислений (и гораздо меньше анонимных перечислений). На данный момент я использую cpp:type:: для типа enum, а затем список всех возможных значений и их описание, но это не кажется идеальным способом справиться с ним, тем более что это делает ссылку на определенные значения болезненной (либо я ссылаюсь только на тип, либо добавить дополнительный маркер перед значением).
Есть лучший способ сделать это? И как мне поступить с анонимными перечислениями?
Решение
У проекта на Github, spdylay, похоже, есть подход. Один из заголовочных файлов на
https://github.com/tatsuhiro-t/spdylay/blob/master/lib/includes/spdylay/spdylay.h
имеет такой код:
/**
* @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;
Там некоторое описание того, как они делают это на https://github.com/tatsuhiro-t/spdylay/tree/master/doc, который включает в себя использование генератора API под названием mkapiref.py, можно купить в
https://github.com/tatsuhiro-t/spdylay/blob/master/doc/mkapiref.py
RST, который он генерирует для этого примера,
.. 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.
Вы можете взглянуть и посмотреть, полезно ли это для вас.
Другие решения
Привет Может быть, вы должны рассмотреть вопрос об использовании Doxygen для документации, поскольку она имеет гораздо больше встроенной поддержки c / c ++. если вы хотите сохранить вывод sphinx вашей документации, вы можете вывести из doxygen в формате xml, а затем использовать вздохнуть он возьмет xml и выдаст тот же вывод sphinx, который вы привыкли иметь.
Вот пример документирования enum в формате doxygen с веб-сайта дышать.
//! 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
};
надеюсь это поможет.