Создание Doxygen для чтения с двумя комментариями С++ в качестве разметки

Я пытаюсь настроить автоматическое 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, чтобы включить приведенные выше правила комментариев. Это похоже на страшный объем работы в незнакомом коде.

Любые другие идеи?

Ответы

Ответ 1

Ответ прост: вы не можете.

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

Doxygen не только принимает комментарии, предшествующие декларации. Вы также можете использовать их везде в коде.

Если вы хотите использовать функции doxygen, вам нужно будет обновить комментарии вручную или написать инструмент script/, который ищет объявления и предыдущие комментарии для их изменения.

Вам нужно решить, выбрать один из трех решений (ваши два и script, добавленные в качестве ответа) или не использовать doxygen.

Ответ 2

Вы можете использовать script для изменения комментария к стилю Doxygen, вот простой python script, просто попробуйте:


#!/usr/bin/env python

import os
import sys
import re

def main(input_file, output_file):
    fin = open(input_file, 'r')
    fout = open(output_file, 'w')
    pattern1 = '^\s*//\s.*'
    pattern2 = '^\s*\w.*\s//\s.*'
    for line in fin.readlines():
        if re.match(pattern1, line) != None:
            line = line.replace('//', '///', 1)
        if re.match(pattern2, line) != None:
            line = line.replace('//', '///<', 1)
        fout.write(line)
    fin.close()
    fout.close()

if __name__ == '__main__':
    if len(sys.argv) != 3:
        print 'usage: %s input output' % sys.argv[0]
        sys.exit(1)
    main(sys.argv[1], sys.argv[2])