生成代码文档

Question

我想以简单的格式生成代码文档。关键项是方法签名、成员、构造函数、方法。我正在.NET中使用各种应用程序，并为它们创建文档。我将在每个项目中添加注释。最终结果应该类似于MSDN或Java文档。

因此，我想拿出我的源代码，并生成一些模板，我可以添加注释。我想在不同的应用程序中选择某些类，而不是其他类。

我不是在说intellisense文档。此文档将用于visual之外的参考。AFAIK，这是在.NET中所有的XML注释都有好处的地方。

我正在记录各种接口和入口点，以便为第三方应用程序编写扩展。我们不拥有它们的代码，所以我不能直接将XML注释附加到它们的接口、类等。相反，我需要实现接口并对其进行注释。然后把它记录在网上。文档化每个实现仅仅是为了解释它们的架构是多余的。他们不记录他们的东西.这才是核心问题。

是否有任何工具可以帮助这一过程？你有什么建议？

Answer 1

含氧非常擅长将XML转换成人类可读的格式，例如MSDN样式的HTML或HTML。(chm)它将使用Visual生成的XML以及您自己创建的XML或从其他来源获取的XML。

另一种选择是沙堡和SCHFP，尽管这减少了维护。

在这两种情况下，您都可以扩展XML标记，而不仅仅是针对Intellisense，包括仅用于外部文档的注释，等等。

Answer 2

我用NaturalDocs。优点(我认为名称)来源于这样一个事实，即它主要根据间距而不是标记来推断格式。你不需要用大量的<method>和类似的东西来修饰你的评论，这样的评论在“野外”中就更加可读性了。

NaturalDocs的评论应该类似于：

/* Function:  my_method
 * 
 * Accepts a Turing machine and an infinite data tape, and determines
 * whether it will halt.
 *
 * Parameters:
 *   turing_id - The ID of a valid Turing machine.
 *   tape_ptr  - A pointer to the start of the inifite-length tape.
 *
 * Returns:
 *   If the machine halts, returns 0.  If the machine doesn't halt,
 *   return value is undefined.
 */
extern int my_method(turing_id_t turing_id, void *tape_ptr);

NaturalDocs会接受这一点，并生成一个具有适当签名、方法描述、表格式的参数列表以及任何附加部分(这里的Returns)的HTML。它还将生成默认按文件组织的目录。您还可以根据Function以外的类型(如Types、Macros等)对事物进行分组。

我可能听起来太热情了，但是当我们换到NaturalDocs的时候，它把大量的样板从我们的头上敲了出来，使它们看起来更像.(咳嗽)自然的。