如何跨不同语言/环境整合文档？答案

【问题标题】：How to consolidate documentation across different languages/environments?如何跨不同语言/环境整合文档？
【发布时间】：2011-03-05 17:21:29
【问题描述】：

我正在设计一个旨在解决广泛问题的类库。关于这个库的一件事是它可以被多种不同的语言和环境本地使用。例如，将有一个完全用 C++ 编写的 C++ 版本、一个用 C# 编写的 .NET 版本和一个用 Java 编写的 Java 版本，彼此之间没有任何依赖关系……而不是用 C++ 编写核心库并简单地提供.NET 和 Java 绑定到它。

每个不同形式的库都致力于解决不同但有时非常相似的问题。例如，可能有许多类的成员在每种语言中的功能相同，并且也有许多类只存在于库的一种或两种语言版本中，而其他语言版本中则不存在。取一个代表程序版本号的类或结构。 .NET 已经有这样的类 (System.Version)，所以我不会将它包含在我的 .NET 版本中，但 C++ 和 Java 库会提供一个。

我面临的问题是，对于大多数或所有版本的库中都存在的类，文档将保持相对相同（显然）。 Version 结构的 C++ 和 Java 版本的简短文本类似于“以major.minor.build.revision 形式表示软件版本号”......详细的类描述和所有成员也是如此文档等。如您所知，.NET、Java 和 C++ 都有自己的文档语法。有什么方法可以尝试以一种语言中立的方式整合文档（不将文档与源代码分开编写 - 例如手动文档，而不是使用 doxygen/sandcastle/javadoc 生成它）还是我卡住了复制和粘贴每个版本的源文件中的文本是否相同？

【问题讨论】：

+1，但我不会说 C++ 有自己的文档语法，除非您指的是 doxygen - 但 doxygen 的大量语法配置选项使其几乎没有成为标准。

标签： language-agnostic documentation documentation-generation

【解决方案1】：

我遇到了同样的问题，并决定只有两种选择：

在所有语言中使用相同的documentation generator。如果您对所有这些都使用 doxygen（或 ROBODoc 或其他），那么您将只有一种适用于所有语言的 doc 语法。不过，这意味着您必须打破特定于语言的约定。
编写您自己的文档解析器。这是一项艰巨的工作，尤其是对于语法规则非常复杂的语言（如 C++）。

我们目前正在将 doxygen 用于此类项目。

【讨论】：

我想我别无选择，只能复制。代码本身将在不同语言之间“重复”，所以我想这样做对于文档也不会太糟糕。