Я пытаюсь настроить автоматическое Doxygen на нашей массивной 78 000 файловой кодовой базе С++. Это хорошо справляется с извлечением информации о базовом типе и иерархии, но я хотел бы сделать умнее собирать комментарии к документации, которые уже существуют.
Большинство комментариев, накопленных за эти годы, следуют общей схеме, хотя и не та, которую ожидал Doxygen. В основном они выглядят как
// class description
class foo
{
// returns ascii art of a fruit
const char* apples( void );
// does something to some other thing
customtype_t baz( foo &other );
enum
{
kBADGER, // an omnivorous mustelid
kMUSHROOM, // tasty on pizza
kSNAKE, // oh no!
};
}
Которые являются двойными, а не комментариями стиля ///
или //!
, которые ожидает Doxygen.
Слишком много файлов для поиска и замены всех таких комментариев, и многие из моих программистов сильно страдают аллергией на просмотр тройных слэшей в своем коде, поэтому я хотел бы найти способ сделать Doxygen чистым как комментарии JavaDoc, когда они находятся в правильном месте. Есть ли способ сделать Doxygen прочитанным //
как ///
?
Я не смог найти такой параметр конфигурации, поэтому, полагаю, мне нужно каким-то образом преобразовать вход. В общем правило я бы использовал:
- если есть строка, содержащая только
комментарий, непосредственно предшествующий
функция/класс/тип/переменная
декларации, предположим, что это
///
комментарий. - если есть декларация
затем в той же строке с помощью
//
комментарий, рассматривайте его как///<
Но я не знаю, как идти о преподавании Doxygen это правило. Двумя способами, о которых я могу думать, являются следующие:
- Напишите программу как INPUT_FILTER, которая анализирует вход С++ и преобразует
//
в///
, как указано выше. Но этот вид преобразования слишком сложный, чтобы делать это как регулярное выражение, и я действительно не хочу писать полномасштабный синтаксический анализатор С++ только для подачи ввода на другой парсер С++! Кроме того, разворачивание программы INPUT_FILTER для каждого файла замедляет Doxygen неприемлемо: для работы над нашим источником уже требуется более 30 минут, а добавление INPUT_FILTER заставляет его принимать более шести часов. - Измените исходный код Doxygen, чтобы включить приведенные выше правила комментариев. Это похоже на страшный объем работы в незнакомом коде.
Любые другие идеи?