使用相同的代码生成2种语言的文档

2023年1月18日 202次阅读

我可以用不同的方式生成2种不同语言的文档吗？问题是我有一个C API,它也通过类似VB的专有语言暴露.

所以C中的暴露函数是这样的：

int Function (*PointerToObject)

在VB中它会是这样的：

int Function (ByVal long PointerToObject)

关于同样的问题,我之前已经打开了another thread,但到那时我对Doxygen一无所知.最近几天我一直在阅读文档,显然它可以为VB创建文档,但我必须有实际的VB代码才能工作,我不这样做.我唯一拥有的是C中的原始C和swig输出.

我想到的是一些工具(doxygen,sphinx,…),这使我能够从单一来源创建某种多语言文档(不是有效的doxygen,但解释了这个想法)：

/*! \fn int Function(*PointerToObject) 
 *  \brief A simple function.
 *  \Cparam[in] PointerToObject A pointer to the object being used.
 *  \VBparam[in]    ByVal long PointerToObject      A pointer to the object being used.
 *  \return An integer.
 */

如果我可以以某种方式将它集成到swig,那将是很好的,因为它是标识正确的VB类型的swig,但我想我可能要求太多.

这有点复杂,如果我不够清楚,请发表评论我将尝试进一步解释.

最佳答案 我并不认为这将是多么有用,因为我没有完全按照你的要求做什么(而且它有点像kludge),但在类似的情况下,我得出结论,我们最好的选择是产生一个绒毛的对象只是为了doxygen文件.

在我们的例子中,我们有一个LDMud,它有几百个驱动程序发布的外部函数,在LPC语言中不存在MUD的其余部分.我们可以在其本机C代码中解析它作为单独的文档运行和include文档与我们的主要文档.在我们的例子中,我们有相当详尽的纯文本文档,包括我们应该考虑这些函数的定义,所以我们使用这个文档来生成一个带有虚函数定义的对象,并将明文文档解析为doxygen中的函数头注释样式.这显然不能为我们提供在文档中包含代码或代码内注释的优势,但它确实允许我们以多种形式生成文档,在指南中推送它,从其他文档引用这些函数等等.

我不是直接熟悉C所以我不确定是否有任何内省的支持来执行您需要的功能的程序化清单,以及是否从该信息生成虚拟声明.如果你没有,并且有少量的功能,我怀疑你只需要手工编写虚拟声明就是最好的投资.如果你有大量的这些函数,可能值得花时间使用doxygen将原始代码解析为XML文档,并从XML生成虚拟对象. Doxygen的XML可能很难处理,但如果您真正需要的是声明和参数,那么(相对)简单.

最后,如果您的文档确实可以被视为内部和外部,您可能还需要使用两个或更多配置文件来生成保存到不同位置的不同文档集,并将它们单独发布到内部/外部受众.它将为每个不那么令人沮丧的事情提供适当数量的细节.沿着这些方向,您还可以找到INTERNAL_DOCS选项和@internal/@endinternal命令.

点赞