5

我可以以某种方式使用相同的代码为 2 种不同的语言生成文档吗？问题是我有一个 C API，它也通过类似于 VB 的专有语言公开。

所以 C 中的暴露函数类似于：

int Function (*PointerToObject)

在 VB 中，它会是这样的：

int Function (ByVal long PointerToObject)

我之前已经针对同样的问题打开了另一个线程，但到那时我对 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，但我想我可能要求太多了。

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

4

1 回答 1

2

我不确定这会有多大用处，因为我没有准确地完成您正在寻找的事情（而且这有点混乱），但在类似的情况下，我得出的结论是，我们最好的选择是生成仅用于 doxygen 记录的绒毛对象。

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

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

As a final aside, if your documentation can really be thought of as internal and external, you might also want to use two or more configuration files to generate different sets of documentation saved to different locations and publish them separately to your internal/external audiences. It will make the task of providing the right amount of detail to each less frustrating. Along those lines you may also find the INTERNAL_DOCS option and the @internal / @endinternal commands useful.

于 2012-12-22T07:11:37.707 回答