Question

我正在开发一个大型的C ++程序，现在我决定用Doxygen来记录它。有很多类，方法，函数，宏等。因此，我正在搜索将扫描我的源代码树并在每个“可记录项目”之上插入Doxygen注释块的软件，以便我稍后编辑它们并添加方法描述等详细信息。

是否存在此类软件？

我使用Code :: Blocks IDE在GNU / Linux下，因此不需要Visual Studio插件。

Answer 1

我在这里很困惑。

自动生成评论的目标是什么？

评论意味着带来额外的价值：

/**
 * \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集合似乎正在进行某种声音识别......
我知道它的名字，所以我可以在互联网上查看它的实现（功能）
我知道为什么它被选中，因此我应该重新评估它的用途（适合西欧客户，所以如果我们在阿拉伯市场上发展它就需要适应......）

不幸的是，这不会自动生成。

Answer 2

好的，所以这是一个老帖子，但我遇到了同样的问题，我发现了doxymacs。它与emacs很好地集成，并为您的函数和文件生成doxymacs注释。将.el文件放入emacs路径后，只要打开C / C ++文件“（add-hook'c-mode-common-hook'doxymacs-mode）”并添加注释，就可以添加一个钩子使其可用。使用Cc df和带有Cc di的文件，还有其他可用的注释类型，只需检查项目页面：http://doxymacs.sourceforge.net/

Answer 3

你可以设置Doxygen来提取未记录的项目 - 这可能会做你想要的，而不会在代码中添加任何注释块。

之后，您可以创建模板/宏（取决于您的IDE），为每种类型的项目创建预先格式化的块，同时逐步完成逐个记录项目的代码。

[编辑] 如果您正在使用Visual Studio，则可以对文件中的类和其他构造进行一些内省，这可能会有所帮助。或者看看Doxycomment - 它可能是你想要的一些。

Answer 4

python中有一些c / cpp解析器，可能用于您的特定目的。但是，我还没有用过那些。

对于类似的目标，我编写了一个python脚本，主要为头文件中的方法添加“doxygen-headers”。我使用了正则表达式，并且我在源文件中为方法定义添加了“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-tool检查 doxygen-headers-added-file ，使用 original-header-file 。

示例： meld file.h file.h.doxygen

注意:: 脚本可能会跳过构造函数，新版本的定义/声明如：

S（）：n（7））{};

Answer 5

genDoxygenC.py的发布有很多索引/空白错误。由于Python程序流依赖于正确的索引，我担心addDoxygenComment方法的内部块可能不正确。您是否有可能将实际的源文件发布到此处？

Answer 6

还有一个用于C ++的免费Doxygen生成器，它使用Visual Studio 2015的宏浏览器插件，可在此处找到： https://github.com/cppocl/visual_studio_macros

Answer 7

检查您的编辑器。我一直在使用CodeWright编辑器，它具有称为选择性显示的功能。配置正确后，我可以按该图标，并且仅显示功能定义的第一行。另外，您可以在其他一些编辑器中使用块折叠/展开。无论哪种方式，都可以轻松快速地在源代码中导航至标头/定义等，然后粘贴一些样板注释以备后用。我经常使用自己的搜索标签，例如在我的代码中 COMMENTME ，我可以通过简单的搜索返回。

任何自动生成doxygen注释块的软件？

7 个答案: