Question

可能重复：
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)
{
   [...]
}

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

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

Answer 1

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

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

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

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

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

Answer 2

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

首先，您必须选择源内文档样式。您可以使用“原生”评论，JavaDoc或XMLDoc。选择文档样式后，您应该选择文档标准。

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

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

我还是喜欢XMLDoc样式和Delphi Documentation Guidelines。这是主观的。我假设现在最好的XMLDoc Delphi文档生成器是 Doc-O-Matic 。它还支持JavaDoc样式，我目前正在试验它。它不支持Delphi Documentation Guidelines中提到的所有标记，例如它不支持＆lt; list＆gt;标签，但你可以使用＆lt; para＆gt;而是生成可敬的文档。

尝试可用的内容并选择您喜欢的内容。

Answer 3

如果您只想根据功能评论记录源代码，我建议您使用Doc-O-Matic。

但真正的问题是：你应该记录你的源代码吗？我不这么认为。根据TDD和XP，您根本不应该评论您的代码。您的代码应包含真正指示过程执行操作的良好过程名称。所以你可以考虑不记录它，只需重构它就可以很容易理解。

Delphi的CODE文档创建工具

3 个答案: