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

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

来源

2010-06-19 Jake Petroules

+1，但我不会说C++有自己的文档语法，除非你的意思是doxygen--但doxygen的大量语法配置选项使它几乎不是一个标准。 – soulmerge 2010-06-19 07:40:02

我有同样的问题，并决定确实是给我只有两个选择：

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

我们目前正在为这样的项目使用doxygen。

来源

2010-06-19 07:46:35 soulmerge

我想我别无选择，只能重复。代码本身会在不同语言中“重复”，所以我想这样做对于文档来说也不会太糟糕。 – 2010-06-19 22:29:51

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

回答

相关问题