使用Doxygen和非Doxygen创建文档注释的源代码
我们在这里得到了一些像10年前的C和C++代码,没有文档或手册。然而,头文件中记录的源代码相当不错,但通过所有查找信息的文件需要很多工作。它看起来像这样:使用Doxygen和非Doxygen创建文档注释的源代码
// Description description ....
//
// @param parameter 1 name:
// description of parameter 1
//
// @param parameter 2 name:
// description of parameter 2
//
Returntype Functionname(parameter1, parameter2);
使用doxygen的向导文件可以被创建,但所有的评论都将丢失,因为它们不是在某种程度上分析器理解格式化。
那么是我不知道的格式?我可以教解析器做什么?或者它是另一种软件使用的特殊格式?
我写了一个python脚本,将注释转换为解析器可以理解的格式。这不太好,不安全,但对我们很有用。
import re
import time
import os
import shutil
def convertHeaderDocumentation(file):
with open(file) as f:
lines = f.readlines()
lines = [line.rstrip('\n') for line in lines]
scanning = False
commentLines = []
convertedDocument = ""
declaration = ""
for line in lines:
if line == "" or \
line.strip().startswith("#"):
if len(commentLines) > 0:
convertedDocument += ''.join(el + "\n" for el in commentLines)
commentLines.clear()
convertedDocument += line + "\n"
continue
if line.strip().startswith('//'):
if not scanning:
commentLines.clear()
scanning = True
commentLines.append(line)
else:
if scanning:
if line.strip() != "":
declaration = line.strip()
match = re.search('\s*\w*\s*(\w+)\s+(\w+).*\((.*)[^)].*;', declaration)
if not match is None:
# check for function description
description = ""
for line in commentLines:
if line[2:].strip().startswith("@") or \
line[2:].strip() == "":
break
else:
description += line[2:].strip()
# scan for parameter description
parameters = []
parameter = ""
scanning = False
for line in commentLines:
# start scanning, if line starts with @
if line[2:].strip().startswith("@") and \
scanning == False :
# if present add to parameter lst
if parameter != "":
parameters.append(parameter)
scanning = True
parameter = line[2:].strip() + " "
continue
# stop scanning if an empty line is read
if line[2:].strip() == "":
scanning = False
# save if parameter is in buffer
if parameter != "":
parameters.append(parameter)
parameter = ""
if scanning == True and line[2:].strip() != "":
parameter += line[2:].strip()
convertedDocument += "/**\n"
convertedDocument += " * @fn " + declaration[:-1] + "\n"
convertedDocument += " *\n"
convertedDocument += " * @brief "
restLine = 80 - len(" * @brief ")
for index in range(0, len(description), restLine):
convertedDocument += description[index:index + restLine] + "\n * "
convertedDocument += "\n"
for parameter in parameters:
convertedDocument += " * " + parameter + "\n *\n"
convertedDocument += " * @return " + match.group(1) + "\n"
convertedDocument += " *\n"
convertedDocument += " * @date " + time.strftime("%d.%m.%Y") + "<br> parsed using python\n"
convertedDocument += " */\n"
convertedDocument += declaration + "\n\n"
commentLines.clear()
else :
convertedDocument += ''.join(el + "\n" for el in commentLines)
commentLines.clear();
return convertedDocument
projectDir = "path to source files goes here"
projectDir = os.abspath(projectDir)
parentProjectDir, projectDirName = os.path.split(projectDir)
convertedDir = os.path.join(parentProjectDir, "converted")
print(convertedDir)
for root, dirs, files in os.walk(projectDir):
# create directory structure if not present
tmpConvertedDir = os.path.join(convertedDir, root[len(projectDir) + 1:])
if not os.path.exists(tmpConvertedDir):
os.makedirs(tmpConvertedDir)
for file in files:
filename, fileextension = os.path.splitext(file)
# only copy/convert c++/c source files
if fileextension in {'.h','.c','.cpp'} :
newPath = os.path.join(tmpConvertedDir, file)
print(newPath)
# convert header files
if fileextension in {'.h'}:
#print("convert ", os.path.join(root, file), " to ", newPath)
converted = convertHeaderDocumentation(os.path.join(root, file))
with open(newPath, 'w') as f:
f.write(converted)
# copy source files
else:
print("copy ", os.path.join(root, file), " to ", newPath)
shutil.copyfile(os.path.join(root, file), newPath)
功能声明有点棘手,赶上正则表达式。对于我来说, \s*\w*\s*(\w+)\s+(\w+).*\((.*)[^)].*;
作品就好了,但没有任何额外的关键字惰性限定符将是关键字更acurate的的返回类型之前,在给定的PROJECTDIR目录\s*\w*?\s*(\w+)\s+(\w+).*\((.*)[^)].*;
所有的C和C++的文件和子文件夹被转换,如果他们头文件或只是复制源文件。因此将创建一个包含复制/转换文件的目录.. \转换。
使用生成的文件doxygen向导创建了足够的文档。也许这会帮助某人:-)
请看看[我可以回答自己的问题吗?](http://*.com/help/self-answer),并在两天后回来查看回答。 –
谢谢,下次我会记住这一点。 – Aeonos
你可以创建一个脚本,用'//!'或其他一些doxygen注释代替'//'。 – Serge