Заставить Doxygen читать комментарии C ++ с двойной косой чертой как разметку

Question

Я пытаюсь настроить автоматизированные Doxygen , работающие на нашей огромной базе кода C ++ на 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 этому правилу. Два способа, о которых я могу думать:

1. Напишите программу как INPUT_FILTER , которая анализирует входные данные C ++ и преобразует // s в /// s, как указано выше. Но этот вид преобразования слишком сложен, чтобы его можно было использовать как регулярное выражение, и я действительно не хочу писать полноценный синтаксический анализатор C ++ только для того, чтобы передавать ввод в другой синтаксический анализатор C ++! Кроме того, раскрутка программы INPUT_FILTER для каждого файла замедляет недопустимо замедление Doxygen: для работы с нашим источником уже требуется более 30 минут, а добавление INPUT_FILTER делает это более шести часов.
2. Измените исходный код Doxygen, включив в него вышеприведенные правила комментариев. Это кажется страшным количеством работы в незнакомом коде.

Есть еще идеи?

Answer 1

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

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

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

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

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

Answer 2

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

#!/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])