Delphi 的 CODE 文档创建工具
我想开始记录一个非常大的 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、标准等。
Possible Duplicate:
Code documentation for delphi similar to javadoc or c# xml doc
I want to start documenting a very large Delphi application, which currently has no documentation whatsoever. My coworker suggested a javadoc type documentation style because we can then run an automated program to create nice documentation which is searchable and looks pretty.
(* 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)
{
[...]
}
Is this the best way I can accomplish meaningfull documentation for my project? If so what is a good program to handle these types of comments . So far I have had Doc-O-Matic recommended to me.
If it is any use the program is very old, it has been constantly developed since 1993 or so and has gone though many different authors, many different styles, IDEs, standards, etc.
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（3）
看一下 SynProject，这是一个用 Delphi 编写的开源工具。
它旨在处理完整的文档工作流程，从规范到发行说明，包括测试、架构和设计；当然，还有一个集成的 Delphi 解析器，可以从现有的 Delphi 源代码生成体系结构文档。
对于架构文档，源代码可以提取注释（ala JavaDoc），然后将此文本嵌入到主架构文档中（带有类层次结构图和单元依赖关系）。
您可以在专用文本编辑器中使用类似于 wiki 的语法编写纯文本文件，然后 SynProject 从中创建格式良好的 Word 文档。某些向导可用于访问内容。但由于它存储为纯文件，因此多个程序员可以使用任何 SCM 工具（SVN、Fossil...）在其上写入。
例如，我目前使用它为一个巨大且旧的 Delphi 应用程序（大约 2,000,000 行用 Delphi 5 和 6 编写的代码）编写维护文档，之前没有可用的文档。您描述对代码所做的更改（通过引用单元/类/方法），然后该工具将更新所有文档以反映和跟踪这些修改。 SynProject 的设计符合一些非常“微妙”的监管规则（IEC 62304），但由于其独特的“扁平”设计，可用于任何项目。
Take a look at SynProject, an Open Source tool written in Delphi.
It was designed to handle a full documentation workflow, from specifications to release notes, including tests, architecture and design; and of course there is an integrated Delphi parser to generate architecture documentation from existing Delphi source code.
For the architecture document, the source code can extract comments (ala JavaDoc) then embed this text into the main Architecture document (with class hierarchy diagrams and unit dependencies).
You write a plain text file using a wiki-like syntax in a dedicated text editor, then SynProject creates well formated Word documents from it. Some Wizards are available to access the content. But since it's stored as plain file, multiple programmers can write on it, using any SCM tool (SVN, Fossil...).
For instance, I currently use it for writing maintenance documentation for a huge and old Delphi application (about 2,000,000 lines of code written in Delphi 5 and 6), with no prior available documentation. You describe the changes made to the code (by quoting the unit/class/method), then the tool will update all documentations to reflect and trace those modifications. SynProject was designed to be compliant with some very "delicate" regulation rules (IEC 62304), but can be used for any project due to its unique "flat" design.
创建源内文档没有“最佳方法”。因此，任何答案在某种程度上都是主观的。
首先，您必须选择源内文档样式。您可以使用“本机”注释，
JavaDoc或XMLDoc。选择文档样式后，您应该选择文档标准。此外，您还需要一个文档生成器来发布您的源内文档（html、pdf 或其他格式）。
对于 Delphi 源代码，目前最支持
JavaDoc样式。我尝试了 DelphiCodeToDoc （它使用JavaDoc）来生成 html 文档，并且它有效。我认为您可以找到更多支持JavaDoc的 Delphi 源文档生成器。我仍然更喜欢
XMLDoc风格和 Delphi 文档指南。那是主观的。我认为现在最好的XMLDocDelphi 文档生成器是 Doc-O-Matic。它还支持JavaDoc风格，我目前正在尝试它。它不支持 Delphi 文档指南 中提到的所有标签，例如它不支持;标签，但您可以使用;相反并生成值得尊敬的文档。
尝试可用的内容并选择您更喜欢的内容。
There are no "best ways" for creating in-source documentation. Consequently, any answer will be subjective to some extent.
First of all you must choose your in-source documenting style. You can use either "native" comments,
JavaDocorXMLDoc. After choosing the documenting style you should choose the documenting standards.Also you need a documentation generator to publish your in-source documentation (in html, pdf or other format)
As for Delphi source code, currently
JavaDocstyle is the most supported. I tried DelphiCodeToDoc (it usesJavaDoc) to generate html documentation, and it works. I think you can find more documentation generators for Delphi sources supportingJavaDoc.Still I prefer
XMLDocstyle and Delphi Documentation Guidelines. That is subjective. I assume that the bestXMLDocDelphi documentation generator now is Doc-O-Matic. It also supportsJavaDocstyle, I am currently experimenting with it. It does not support all the tags mentioned in Delphi Documentation Guidelines, for example it does not support <list> tag, but you can use <para> instead and generate respectable documentation.Try what is available and choose what you like more.
如果您只想根据函数注释来记录源代码，我建议您使用 Doc-O-Matic。
但这里真正的问题是：你应该记录你的源代码吗？我不这么认为。根据 TDD 和 XP，你根本不应该注释你的代码。您的代码应该包含良好的过程名称，真正表明该过程的作用。所以你可以考虑不记录它，只是重构它，以便它可以很容易理解。
If you just want to document your source code based on functions comments, I would recomend you to use Doc-O-Matic.
But the real question here is: should you document your source code? I dont think so. According to TDD and XP, you should not comment your code at all. Your code should contains good procedures names that really indicates what the procedure does. So you could consider not document it, just refactor it so it can be easily understandable.