Как расширить макросы с помощью doxygen, но не документировать их как определение?

Скажем, у меня есть:

#define MY_MACRO(FOO) void FOO();

MY_MACRO(hi);
MY_MACRO(hey);
MY_MACRO(hello);

#undef MY_MACRO

Я хочу, чтобы макросы были расширены с помощью doxygen, что я могу сделать, настроив его правильно:

ENABLE_PREPROCESSING   = YES
MACRO_EXPANSION        = YES
EXPAND_ONLY_PREDEF     = YES
EXPAND_AS_DEFINED      = MY_MACRO

Это позволяет мне видеть расширенный результат макросов в виде документированных API в выходных данных doxygen (функции hi, hey и hello). Пока все хорошо. Но проблема в том, что doxygen также документирует MY_MACRO как определение. Однако я не хочу, чтобы клиенты API знали о MY_MACRO, так как он не защищен и не может использоваться ими и не должен быть им виден.

У меня есть EXTRACT_ALL = YES в моей конфигурации doxygen, и я не хочу это менять. Я безуспешно пробовал следующую конфигурацию:

PREDEFINED      = DOXYGEN_SKIP_FOR_USERS

Со следующим кодом:

#ifndef DOXYGEN_SKIP_FOR_USERS
#define MY_MACRO(FOO) void FOO();
#endif /*DOXYGEN_SKIP_FOR_USERS*/

MY_MACRO(hi);
MY_MACRO(hey);
MY_MACRO(hello);

#undef MY_MACRO

Это скрывает документацию определения, но, конечно, предотвращает расширение, поэтому я не получаю функции, задокументированные в сгенерированном API.

Я был бы признателен за вашу помощь.


person Buğra Gedik    schedule 17.09.2010    source источник


Ответы (1)


Предположим, что MY_ — это префикс, который вы постоянно используете в своем коде :) Я бы использовал префикс MY__ (два символа подчеркивания) для внутренних макросов, а затем добавил что-то вроде

EXCLUDE_SYMBOLS        = MY__*

в файле конфигурации Doxygen.

Изменить: двойное подчеркивание внутри символов зарезервировано для C++ (не для C). Поэтому, если вы хотите быть совместимым с C и C++, вам следует выбрать другой тип соглашения. К сожалению, ведущее подчеркивание также зарезервировано, поэтому _MY_ не подходит ни для того, ни для другого.

person Jens Gustedt    schedule 17.09.2010
comment
Примечание о двойном подчеркивании: имена, содержащие двойное подчеркивание, зарезервированы для использования компилятором. Чтобы не наступать друг другу на пятки, лучше не использовать двойное подчеркивание в собственных идентификаторах. - person Bart van Ingen Schenau; 17.09.2010
comment
@Bart У тебя есть под рукой цитата? Я думал, что это только идентификаторы, начинающиеся с двойного подчеркивания. (И вообще глобальные идентификаторы, начинающиеся с подчеркивания, и т.д.) - person llasram; 17.09.2010
comment
@Bart и @llasram: я думаю, что это правило двойного подчеркивания является правилом C++, а не для C (я не заметил флаг C++). Но в любом случае для той цели, о которой мы здесь говорим, можно легко подобрать какой-нибудь другой, не слишком противный, префикс. - person Jens Gustedt; 17.09.2010
comment
Я не вижу EXCLUDE_SYMBOLS в документации doxygen по адресу: stack.nl/~dimitri/doxygen /config.html - person Buğra Gedik; 17.09.2010
comment
@bugur: да странно, что там это не задокументировано. Но он появляется и задокументирован в файле конфигурации по умолчанию, который создает doxygen. - person Jens Gustedt; 17.09.2010
comment
Я создал элемент bugzilla в документации. - person Buğra Gedik; 17.09.2010
comment
@Jens и @llasram: двойное подчеркивание действительно только для C++ и указано в пункте 17.4.3.1.2 стандарта C++. Для меня вопрос стоил того, чтобы прокомментировать его, но не стоил отрицательных голосов. - person Bart van Ingen Schenau; 18.09.2010
comment
@Bart: Я никогда не думал, что ты это сделаешь. За двойное подчеркивание, спасибо, что выкопали это. Это звучит разумно для C++, он должен оставить соглашения об именах для искажения имен функций. Я отредактирую свой ответ, чтобы людям не приходилось делать это через комментарии. - person Jens Gustedt; 19.09.2010