如何为 Java、C# 和 C++ 中一个项目的不同实现管理一份一致的文档？ [关闭]

Posted 2023-02-22

【中文标题】如何为 Java、C# 和 C++ 中一个项目的不同实现管理一份一致的文档？ [关闭]

【英文标题】：How to manage one consistent documentation for different implementations of one project in Java, C# and C++? [closed]

【发布时间】：2014-03-17 12:26:48

【问题描述】：

如何在 Java、C# 和 C++ 中为一个项目的不同实现管理一份一致的文档？

我们的项目需要提供 Java、C# 和 C++ 版本。

我们面临的一个问题是文档。 C++ 版本是我们的主要版本。 然后我们将更改传播到 C# 和 Java 版本。每次我们做 对 C++ 版本的更改我们需要对 Java 和 C# 版本执行相同的操作。 有没有办法解决这个问题？

为了记录 C++ 和 C#，我们使用 Visual Studio，Java 版本使用 javadoc。

【问题讨论】：

您可能需要查看Doxygen 以获取文档。我不认为它具有您正在寻找的自动传播行为，但它至少可以为您提供跨语言的一致性，因为它支持您正在使用的所有三种语言。

这可能吗？像public <T> void f(Collection<T> x) 这样的惯用Java 签名在C++ 中可能看起来像template<typename It> void f(It begin, It end)。 f 的统一文档是什么样的？

IEnumerable<T> 与迭代器对是完全不同的野兽。

@DeadMG 你同意还是不同意我的观点？ :)

【参考方案1】：

您可以使用Doxygen，它提供统一的、独立于语言的语法，适用于 C++、Java 和 C#。

【讨论】：

Doxygen 产生的废话并不比仅仅阅读源代码或自己查看代码完成列表提供更多信息。

@DeadMG：当然，如果你给它提供垃圾文档。

【参考方案2】：

我更喜欢使用源代码管理工具来解决这个问题。

我为每个不同的语言项目创建单独的 Git 存储库。在这种情况下，我将从 C++ 存储库开始，然后为 Java 和 C# 代码创建其他存储库。

由于 C++ 代码是“主”（或参考）版本，我将打开 C# 存储库并为 C++ 代码添加一个新的 Git 子模块。此子模块将始终表示您的 C# 库与 C++ 库相比的“最新”程度。对 Java 库的存储库执行相同操作。

对 C++ 代码（包括文档）进行更改后，您可以检查 C# 和 Java 目标的子模块。这些子模块将向您展示自上次更新 C# 或 Java 代码以来对 C++ 库所做的提交，使您可以轻松地应用和/或验证其他语言的更改。当您提交对 C# 或 Java 库的更改时，您可以更新子模块引用以指向 C++ 库中新的“最新”提交。

此工作流程的巨大优势在于始终告知整个团队每个库是否是最新的，如果不是，确切地需要进行哪些更改才能对其进行更新。