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

Question

我能否以某种方式使用相同的代码为 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，但我想我可能要求太多了。

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

Answer 1

我不确定这会有多大用处，因为我没有完全按照您的要求进行操作（而且有点杂乱无章），但在类似的情况下，我得出的结论是我们最好的选择是为 doxygen 生成一个绒毛对象来记录。

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

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

最后，如果您的文档真的可以被认为是内部和外部的，您可能还想使用两个或多个配置文件来生成保存到不同位置的不同文档集并将它们分别发布到您的内部/外部观众。这将使为每个人提供适量细节的任务变得不那么令人沮丧。沿着这些思路，您可能还会发现 INTERNAL_DOCS 选项和 @internal / @endinternal 命令很有用。