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

Question

我可以以某种方式为两种不同的语言生成具有相同代码的文档吗？问题是我有一个C API，该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中，那将是很棒的，因为它是Swig来标识正确的VB类型，但是我想我可能会问太多。

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

Answer 1

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

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

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

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