Любое программное обеспечение для автоматического создания блоков комментариев doxygen?

Ответ 1

Вы можете установить Doxygen для извлечения не документированных элементов, а также - что может делать то, что вы хотите, не добавляя к этому времени еще никаких блоков комментариев.

После этого вы можете создавать шаблоны/макросы (в зависимости от вашей IDE) для создания предварительно отформатированных блоков для каждого типа элемента, так как вы медленно работаете через код, документирующий элементы один за другим.

[править] Если вы используете Visual Studio, некоторые интроспекции доступны для классов и других конструкций в файле, что может помочь. В качестве альтернативы посмотрите Doxycomment - это может быть часть того, что вы хотите.

Ответ 2

Я здесь довольно озадачен.

Какова цель автоматического создания комментариев?

Комментарии предназначены для добавления дополнительного значения:

/**
 * \brief: finds the person based on its name
 * \param: name, the name of the person
 * \result: the person
 */
Person findPerson(Name name);

Это не что иное, как беспорядок кода, который забивает мое ценное свойство экрана. И это примерно так же, как может быть создано автоматически, к сожалению... Обратите внимание, в частности, что я понятия не имею, что произойдет, если функция не найдет человека, что, безусловно, кажется вероятным: отменяет ли он? бросает? (что...?) возвращает построенный по умолчанию объект?

С другой стороны:

///
/// Try an exact match approach to begin with
/// Uses the double metaphone algorithm
///   if none was found as we have
///   a western european clientele
///
Person findPerson(Name name)
{
}

гораздо интереснее!

• Теперь я знаю, что представляет собой эта странная коллекция if, которая, кажется, выполняет какое-то распознавание звука...
• Я знаю его имя, поэтому я могу посмотреть его в Интернете, чтобы проверить его реализацию (функциональность)
• И я знаю, почему он был выбран, и поэтому, когда я должен переоценить его использование (подходит для западноевропейских клиентов, поэтому, если мы развиваемся на арабском рынке, ему потребуется адаптация...)

К сожалению, это не будет автоматически сгенерировано.

Ответ 3

Хорошо, так что это старый пост, но у меня была такая же проблема, и я нашел doxymacs. Он прекрасно интегрируется с emacs и генерирует комментарии doxymacs для ваших функций и файлов. После размещения файла .el в вашем пути emacs вы можете добавить крючок, чтобы сделать его доступным, когда вы открываете файл C/С++ "(add-hook" c-mode-common-hook'doxymacs-mode ")" и прокомментируйте функции с Cc df и файлами с Cc di, существуют другие типы комментариев, просто проверьте страницу проекта: http://doxymacs.sourceforge.net/

Ответ 4

В python есть несколько парсеров c/cpp, которые могут использоваться для вашей конкретной цели. Тем не менее, я еще никогда не использовал их.

Для аналогичной цели я написал python script, который добавляет "doxygen-headers" к методам в заголовочном файле. Я использовал регулярное выражение, и у меня есть версия, которая добавляет "исходные заголовки" в исходный файл для определений методов (используйте метод RE_M_DEFINITION при поиске метода).

Код для справки, как показано ниже:

genDoxygenC.py

#!/usr/bin/python

import os
import sys
import re

################################################################

RE_MULTI_LINE_PARAMS = ".*"

# could be used in header/source files, for method-definition extraction
RE_M_DEFINITION  = r'[A-Za-z0-9*]*\s*[A-Za-z0-9_*]+\s*[A-Za-z0-9_~:*]+\(.*\)\s*\{\s*.*?\s*\}'   #TODO:  this needs to be more generic to                                                        be able to parse for methods only
# used in header-files in major for method declaration extraction
RE_M_DECLERATION = r"[A-Za-z0-9*]*\s*[A-Za-z0-9_*]+\s+[A-Za-z0-9_~*]+\s*\(%s\)\s*;"%RE_MULTI_LINE_PARAMS

################################################################

# C/CPP CMD List
cmdList = ["for","if","while","switch","else"];

##########################
# exit errors enumerations
class EErrors() :
    IncorrectUsage, FileOpenError = range(2)

###################
# exception handler
def handleException(e, mssg) :
    if e == EErrors.IncorrectUsage :
        print "Usage : "+mssg
        elif e == EErrors.FileOpenError :
        print "Unable to open \"" + mssg + "\" file !"
    sys.exit(2)

###############################
# creates method doxygen header 
def frameDoxygenHeader(param_count, paramList) :
    commentStr = "/**\n * @brief \n"    
    if param_count > 0 :
        for param in paramList:
            commentStr = commentStr + " * @param \n"

    # comment for return values
    commentStr = commentStr + " * @return \n */ \n"

    return commentStr

##############################################
# adds the doxygen comments, on method lookup
def addDoxygenComment(file_name, funcList) :
    try:    
        fh = open(file_name, 'rb')
        f_old = open(file_name, 'r+') 
    except:
                handleException(EErrors.FileOpenError, file_name)

    f_new = open(out_file_name, "w")
    final_loc = 0
    next_split_loc = 0
    last_write_loc = 0
    fContent = str(f_old.read())
    for func in funcList:
        SEARCH_TEXT = func  
        print "SEARCH_TEXT "+SEARCH_TEXT
            fsize =  os.path.getsize(file_name)
            bsize = fsize
            word_len = len(SEARCH_TEXT)
        fh.seek(0)

        # doxygen comment header generation
        paramListStr = re.findall(r'\(.*\)', SEARCH_TEXT)
        paramListStr[0] = paramListStr[0].replace('(','')
        paramListStr[0] = paramListStr[0].replace(')','')
        paramList = paramListStr[0].split(",")
        comment_text = frameDoxygenHeader(len(paramList),paramList)

        while True:
                    found = 0
                    pr = fh.read(bsize)
                    pf = pr.find(SEARCH_TEXT, next_split_loc)
                    if pf > -1:
                            found = 1
                            pos_dec = fh.tell() - (bsize - pf)
                            fh.seek(pos_dec + word_len)
                            bsize = fsize - fh.tell()
                print "Case-I:"+str(fh.tell())
                    if fh.tell() < fsize:
                                   seek = fh.tell() - word_len + 1
                                   print "seek"+str(seek)
                       fh.seek(seek)
                                   if 1==found:
                                           final_loc = seek
                           next_split_loc = final_loc + word_len - 1
                                           print "loc: "+str(final_loc)
                       print "Case-IIa:"+str(fh.tell())
                    else:
                                   break

        # create file with doxygen comments
        if final_loc != -1 :
            #f_new.write(fContent[0:final_loc-1]);
            #not to miss the contents, between two methods          
            if last_write_loc < final_loc :
                f_new.write(fContent[last_write_loc:final_loc-1]);

            f_new.write(comment_text);
            f_new.write(fContent[final_loc-1:next_split_loc])
            last_write_loc = next_split_loc

            #reset values
            final_loc = -1
        else:
            print "method not found !!"

    # last of the file should not be missed either
    if last_write_loc < len(fContent) :
        f_new.write(fContent[last_write_loc:]);
    f_new.close()
    f_old.close()


#############################################
#############################################
# main execution of the code starts from here
#############################################
argc = len(sys.argv)
if (argc == 1 or argc >2)  :
    handleException(EErrors.IncorrectUsage, "genDoxygenC.py <cpp source file>")
else :
    # Correct Input as per USAGE.
    fname = sys.argv[1]
    out_file_name = fname+'.doxygen'
    fcontent=''
    try:
        # read file
        fh = open(fname)
        fcontent = fh.read()
    #   print fcontent
    except:
        handleException(EErrors.FileOpenError, fname)

    # lookup for methods in file
    funcList = re.findall(RE_M_DECLERATION, fcontent, re.VERBOSE)
    fh.close()

    funcListCopy = funcList
    for fStr in funcListCopy :
        fStr = fStr.lstrip()
        startW = fStr.partition(' ')[0]
        startW = fStr.partition('(')[0]
        #print startW
        if startW in cmdList :
            # invalid method extraction
            funcList.remove(fStr)   

    # process valid methods-list for doxygen header
    addDoxygenComment(fname, funcList)
    #print funcList

Использование::./genDoxygenC.py file.h

Это приведет к созданию

file.h.doxygen

а затем, возможно, вы можете проверить файл с добавлением добавленного содержимого, с исходным заголовком, используя любой инструмент diff.

Пример: meld file.h file.h.doxygen

Примечание:: script может пропустить конструкторы, например, описания/объявления новых версий;

S(): n (7)) {};

Ответ 5

Публикация для genDoxygenC.py имеет многочисленные ошибки индекса/пробела. Поскольку поток программы Python зависит от правильной индексации, я обеспокоен тем, что внутренний блок может быть неправильным методом addDoxygenComment. Есть ли вероятность, что вы можете разместить фактический исходный файл здесь?