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

Question

我正在设计一个旨在解决各种问题的类库。关于这个库的一件事是它本身可以被几种不同的语言和环境使用。例如，将有一个完全用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生成文档）或者我是否卡在复制和粘贴相同的文本到每个版本的源文件？

Answer 1

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

1. 在所有语言中使用相同的documentation generator。如果对所有语言使用doxygen（或ROBODoc或其他），那么所有语言只需要一种doc语法。这意味着您必须打破特定于语言的约定。
2. 编写自己的doc解析器。这是一项艰苦的工作，特别是对于具有相当复杂的语法规则的语言（如C ++。）

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