Разверните прагму в комментарии (для doxygen) - PullRequest
Новая
       43

Разверните прагму в комментарии (для doxygen)

0 голосов
/ 27 сентября 2018

Комментарии обычно преобразуются в один пробел перед запуском препроцессора.Однако есть убедительный вариант использования. 

#pragma once   

#ifdef DOXYGEN
  #define DALT(t,f) t
#else
  #define DALT(t,f) f
#endif

#define MAP(n,a,d) \
  DALT ( COMMENT(| n | a | d |) \
       , void* mm_##n = a \
       )

/// Memory map table
/// | name | address | description |
/// |------|---------|-------------|
MAP (reg0  , 0       , foo         )
MAP (reg1  , 8       , bar         )

В этом примере, когда установлен флаг DOXYGEN, я хочу сгенерировать разметку doxygen из макроса.Когда это не так, я хочу генерировать переменные.В этом случае желаемое поведение - генерировать комментарии в макросах.Есть мысли о том, как?

Я пробовал /##/, и еще один пример с большей косвенностью 

#define COMMENT SLASH(/)
#define SLASH(s) /##s

ни работает.

Ответы [ 2 ]

0 голосов
/ 27 сентября 2018

В doxygen можно запускать команды на источниках до их подачи в ядро ​​doxygen.В Doxyfile есть несколько возможностей FILTER.В этом случае: INPUT_FILTER строка должна выглядеть следующим образом:

INPUT_FILTER = "sed -e 's%^ *MAP *(\([^,]*\),\([^,]*\),\([^)]*\))%/// | \1 | \2 | \3 |%'"

Более того, вся конструкция #if может исчезнуть, и, возможно, просто потребуется:

#define MAP(n,a,d) void* mm_##n = a

0 голосов
/ 27 сентября 2018

Стандарт ISO C описывает выход препроцессора в виде потока токенов предварительной обработки , а не текста.Комментарии не являются токенами предварительной обработки;они удаляются из входных данных до того, как произойдет токенизация.Поэтому в рамках стандартных возможностей языка принципиально невозможно, чтобы выходные данные предварительной обработки содержали комментарии или что-либо похожее на них.

В частности, рассмотрим 

#define EMPTY
#define NOT_A_COMMENT_1(text) /EMPTY/EMPTY/ text
#define NOT_A_COMMENT_2(text) / / / text
NOT_A_COMMENT_1(word word word)
NOT_A_COMMENT_2(word word word)

После фазы перевода 4,и четвертая, и пятая строки, указанные выше, станут последовательностью из шести токенов 

[/][/][/][word][word][word]

, где квадратные скобки обозначают границы токенов.Токена // не существует, и поэтому вы ничего не можете сделать, чтобы препроцессор его создал.

Теперь стандарт ISO C не определяет поведение doxygen.Однако, если doxygen повторно использует препроцессор, поставляемый с чьим-то компилятором C, люди, написавшие этот препроцессор, вероятно, думали, что текстовый вывод препроцессора должен, прежде всего, быть точным отражением последовательности токенов, которую получит «собственно компилятор».Это означает, что он будет принудительно вставлять пробелы, где необходимо, чтобы отдельные токены оставались отдельными.Например, с test.c приведенным выше примером, 

$ gcc -E test.c
...
/ / / word word word
/ / / word word word

(я исключил некоторую нерелевантную болтовню выше интересующего нас результата.)

Если есть способ обойти этоВы, скорее всего, найдете его в руководстве по Doxygen.Например, могут быть параметры конфигурации, которые учат тому, что определенные макросы следует понимать как определяющие символы, и что это за символы, и какую документацию они должны иметь.

...