gpt4 book ai didi

c++ - 如何避免 c++ 和 boost::python 文档之间的冗余?

转载 作者:塔克拉玛干 更新时间:2023-11-03 01:51:49 25 4
gpt4 key购买 nike

我正在使用 boost::python 在 C++ 代码中添加一个 python 模块。 c++ 项目用 doxygen 记录。我想为 python 模块创建一个文档,但我不知道如何不像这样冗余:

#include <boost/python.hpp>
using namespace boost::python;

/** @brief Sum two integers
* @param a an integer
* @param b another integer
* @return sum of integers
*/
int sum(int a, int b)
{
return a+b;
}

BOOST_PYTHON_MODULE(pymodule)
{
def("sum",&sum,args("a","b"),
"Sum two integers.\n\n:param a: an integer\n:param b: another integer\n:returns: sum of integers");
};

这里我在 docstring 和 doxygen 注释中说同样的话。有什么想法吗?

编辑:c++ 文档不公开,python 接口(interface)是 c++ 的子集。

最佳答案

我是代码生成的粉丝,我相信这是部署它的合理情况。

如果您在编写 Doxygen DocStrings 时有点自律并且避免在其中使用复杂的标记,那么编写一个小型解析器来提取它们并将它们替换回 Python DocStrings 并不难。

这是一个小例子。它的功能不足以处理任何实际用例,但我相信扩展它并不困难并且值得付出努力,除非您只有一大堆功能需要记录。

在每个 Doxygen DocString 之前放置一个特殊注释,为后面的注释 block 命名。在这里,我使用语法

// DocString: sum
/**
* @brief Sum two integers
* @param a an integer
* @param b another integer
* @return sum of integers
*
*/
int sum(int a, int b);

将名称 sum 与以下 DocString 相关联。

然后,在引用该名称的 Python 绑定(bind)中放置另一个特殊字符串。我在这里使用以下语法。

BOOST_PYTHON_MODULE(pymodule)
{
def("sum",&sum,args("a","b"), "@DocString(sum)");
};

现在我们需要一个工具来提取 Doxygen DocStrings 并将它们替换到 Python 绑定(bind)中。

正如我所说,这个例子是人为设计的,但它应该展示这个想法并证明它并不难做到。

import re
import sys

def parse_doc_string(istr):
pattern = re.compile(r'@(\w+)\s+(.*)')
docstring = list()
for line in map(lambda s : s.strip(), istr):
if line == '/**':
continue
if line == '*/':
return docstring
line = line.lstrip('* ')
match = pattern.match(line)
if match:
docstring.append((match.group(1), match.group(2)))

def extract(istr, docstrings):
pattern = re.compile(r'^//\s*DocString:\s*(\w+)$')
for line in map(lambda s : s.strip(), istr):
match = pattern.match(line)
if match:
token = match.group(1)
docstrings[token] = parse_doc_string(istr)

def format_doc_string(docstring):
return '\n'.join('{}: {}'.format(k, v) for (k, v) in docstring)

def escape(string):
return string.replace('\n', r'\n')

def substitute(istr, ostr, docstrings):
pattern = re.compile(r'@DocString\((\w+)\)')
for line in map(lambda s : s.rstrip(), istr):
for match in pattern.finditer(line):
token = match.group(1)
docstring = format_doc_string(docstrings[token])
line = line.replace(match.group(0), escape(docstring))
print(line, file=ostr)

if __name__ == '__main__':
sourcefile = sys.argv[1]
docstrings = dict()
with open(sourcefile) as istr:
extract(istr, docstrings)
with open(sourcefile) as istr:
with sys.stdout as ostr:
substitute(istr, ostr, docstrings)

在源文件上运行此脚本会产生以下输出。

#include <boost/python.hpp>
using namespace boost::python;

// DocString: sum
/**
* @brief Sum two integers
* @param a an integer
* @param b another integer
* @return sum of integers
*
*/
int sum(int a, int b)
{
return a+b;
}

BOOST_PYTHON_MODULE(pymodule)
{
def("sum",&sum,args("a","b"), "brief: Sum two integers\nparam: a an integer\nparam: b another integer\nreturn: sum of integers");
};

为脚本添加两个小时的润色,您就可以开始了。

由于其他人也可能对此感兴趣,因此如果有人已经编写了这样的脚本,我也不会感到惊讶。如果没有,将您的软件发布为免费软件肯定会受到其他人的欢迎。

关于c++ - 如何避免 c++ 和 boost::python 文档之间的冗余?,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/34896122/

25 4 0
Copyright 2021 - 2024 cfsdn All Rights Reserved 蜀ICP备2022000587号
广告合作:1813099741@qq.com 6ren.com