如何整合不同語言/環境下的文檔？

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，或其他），你將只有一種文檔語法的所有語言。這意味着你必須打破語言特定的約定。
2. 編寫您自己的文檔解析器。這是一項艱苦的工作，特別是對於語法規則相當複雜的語言（如C++）。

我們目前正在爲這樣的項目使用doxygen。