Delphi的CODE文档创建工具[重复]答案

【问题标题】：CODE Documentation creation tool for Delphi [duplicate]Delphi的CODE文档创建工具[重复]
【发布时间】：2011-06-23 15:51:16
【问题描述】：

可能重复：
Code documentation for delphi similar to javadoc or c# xml doc

我想开始记录一个非常大的 Delphi 应用程序，它目前没有任何文档。我的同事建议使用 javadoc 类型的文档样式，因为然后我们可以运行一个自动化程序来创建可搜索且看起来很漂亮的漂亮文档。

(* Description of the function            
 @param S        some string
 @param Index    the index of string s
 @retval TRUE    condition where it is true
 @retval FALSE   otherwise.
 @see            IndexOf
 @see            Sort
 @see            Sorted
*)
bool Stringlist::Find(const char *S, int &Index)
{
   [...]
}

这是为我的项目完成有意义的文档的最佳方式吗？如果是这样，什么是处理这些类型的 cmets 的好程序。到目前为止，我已经向我推荐了Doc-O-Matic。

如果有任何用途，该程序已经很老了，它自 1993 年左右以来一直在不断开发，并且经历了许多不同的作者、许多不同的风格、IDE、标准等。

【问题讨论】：

您是在记录应用程序还是它的代码？
我正在记录代码
stackoverflow.com/questions/236047/…的可能重复

标签： delphi documentation javadoc

【解决方案1】：

没有创建源内文档的“最佳方法”。因此，任何答案在某种程度上都是主观的。

首先，您必须选择您的源内文档样式。您可以使用“本机”cmets，JavaDoc 或 XMLDoc。选择文档样式后，您应该选择文档标准。

您还需要一个文档生成器来发布您的源内文档（以 html、pdf 或其他格式）

至于Delphi源码，目前JavaDoc风格是最受支持的。我尝试了 DelphiCodeToDoc（它使用JavaDoc）来生成 html 文档，并且可以正常工作。我认为您可以找到更多支持 JavaDoc 的 Delphi 源文档生成器。

我还是更喜欢XMLDoc 风格和Delphi Documentation Guidelines。那是主观的。我认为最好的XMLDoc Delphi 文档生成器现在是 Doc-O-Matic。它还支持JavaDoc 样式，我目前正在试验它。它不支持Delphi Documentation Guidelines 中提到的所有标签，例如它不支持标签，但您可以使用代替并生成可敬的文档。

尝试可用的，然后选择您更喜欢的。

【讨论】：

【解决方案2】：

如果您只是想根据函数 cmets 记录源代码，我建议您使用 Doc-O-Matic。

但这里真正的问题是：您应该记录您的源代码吗？我不这么认为。根据 TDD 和 XP，您根本不应该评论您的代码。你的代码应该包含好的程序名称，真正表明程序的作用。所以你可以考虑不记录它，只需重构它，让它易于理解。

【讨论】：

我知道没有文档但代码编写良好的伟大项目：例如 KSDev 或 MSEGui。缺少文档对他们来说是一个遗憾！对于大型项目，代码 cmets 或精确的文档是强制性的恕我直言。 VCL 没有注释，但是有参考帮助。此外，记录接口也是一个很好的做法：我通常把它写成规范，然后编写测试，然后编写实现。它完全兼容 XP 或 TDD。您从哪里发现 TDD 或 XP 要求您不要对代码进行注释！ TDD/XP 中没有教条！
嗯，对于一个如此古老的项目，重构将需要几个月的时间并引入许多错误。大约 18 年后，大多数错误已从程序的核心部分中排除。如果我必须在重构和引入错误或仅记录内容之间做出选择，我会选择文档。

【解决方案3】：

看看SynProject，一个用 Delphi 编写的开源工具。

它旨在处理完整的文档工作流程，从规范到发布说明，包括测试、架构和设计；当然还有一个集成的 Delphi 解析器，可以从现有的 Delphi 源代码生成架构文档。

对于架构文档，源代码可以提取 cmets（ala JavaDoc）然后将此文本嵌入到主架构文档中（带有类层次结构图和单元依赖关系）。

您在专用文本编辑器中使用类似于 wiki 的语法编写纯文本文件，然后 SynProject 会从中创建格式良好的 Word 文档。一些向导可用于访问内容。但由于它以普通文件的形式存储，因此多个程序员可以使用任何 SCM 工具（SVN、Fossil...）在其上进行编写。

例如，我目前使用它来为一个庞大而古老的 Delphi 应用程序（大约 2,000,000 行用 Delphi 5 和 6 编写的代码）编写维护文档，之前没有可用的文档。您描述对代码所做的更改（通过引用单元/类/方法），然后该工具将更新所有文档以反映和跟踪这些修改。 SynProject 的设计符合一些非常“精细”的法规 (IEC 62304)，但由于其独特的“扁平”设计，可用于任何项目。

【讨论】：