感谢：破宝 http://blog.joycode.com/percyboy/ <?xml:namespace prefix = o ns = "urn:schemas-microsoft-com:office:office" />

在线资源：NDoc 1.3 中文版用户指南

下载：NDoc中文版安装包下载  NDoc源码下载

NDoc 是一个很好用的.NET小工具，它可以将 C#.NET 编译生成的程序集和对应的 /doc XML 文档，自动转换成如 .NET Framework SDK 类库文档或者 MSDN Library 在线 .NET 类库文档形式的代码文档，让您快速拥有专业级的类库API 文档。(VB.NET 通过第三方插件如 VBCommenter 的支持，也可以生成 XML 文档。)  这里不多说了，现在说说怎么快速使用NDoc生成文档

首先配置我们自己的C#项目，让我们的程序集生成XML文档

<?xml:namespace prefix = v ns = "urn:schemas-microsoft-com:vml" />

注意：XML文档文件名和程序集同名，省去不必要的麻烦；在 NDoc 中，当您加入某程序集时，NDoc 会自动查找这样的“同名” XML 文件。如果找到，就会尝试自动将它当作该程序集的 XML 文档。这样会简化您的操作。

第二步：完善自己的程序的相关注释

比如在一个函数前面输入“///”.NET会自动创建一个 summary XML 文档块:

/// <summary>

///

/// </summary>

/// <param name="s"></param>

/// <param name="s2"></param>

作用也一目了然，生成文档的时候这是很有用的。你的注释越是详细，你生成的文档就会越专业。

这里不得不对比国内和国外的情况了，国内我们的程序员往往花N多时间完成了一个不错的软件或者类库什么的，往往什么文档也没有，别人想学习，想用你的东西，往往被一对烦乱的代码堆砌，吓跑了。那么这个软件或者类库有何意义呢，能给别人带来帮助吗？国外的做法和国内的相差就太大了，他们往往花一半的时间完善他们的注释文档工作，往往10行的小代码段，会有20行的注释，这是很多人无法想象的，但是何为目光短浅，相信聪明人自然明了。

继续说我们的注释，NDoc还支持狠毒其他的标记，需要我们自己输入的，生成文档的时候会看到相应的效果，具体怎么用，往下看。

NDoc支持许多有用的标记，下面有张列表

标记

说明

<event>

[NDoc 扩充]

对某个成员可能引发的事件的说明。

<example>

“示例”，帮助类库使用者理解类型/成员使用方法的示例代码。

<exception>

对某个成员可以抛出的异常的说明。

<exclude/>

[NDoc 扩充]

指示 NDoc 文档引擎将被标记的类型/成员排除在代码文档之外。

与文档引擎的“可见性”配置不符的，以 exclude 优先。

<include>

将代码文件外部的某 XML 文件中的一部分包含进代码文件来。

<overloads>

[NDoc 扩充]

为“重载列表”页面准备摘要、备注、示例等文档内容。只需在重载成员的第一个成员前面书写此区域即可。

<overloads> 标记有两种形式:

· 简单的形式，直接在 overload 中写文本，这些文本被处理为“重载列表”页面的摘要。没有备注、示例等区域。

· 复杂的形式，在 overload 内部，包含 summary, remarks, example 等标记分别表示“重载列表”页面的摘要、备注、示例等。

示例:

///<overloads>This method has two overloads.</overloads>

///<summary>This overload just says hello.</summary>

public void SayHello() { ... }

///<summary>This one says hello to someone.</summary>

public void SayHello(string toSomeone) { ... }

<param>

成员的参数说明。

<permission>

访问某成员所必需的 .NET Framework 安全性 CodeAccessPermission。

<preliminary>

[NDoc 扩充]

将某类型/成员标记为“预发布”。内部的文本被当作警告文本用红色显示，可以包含 <para> 表示多行文本。如果缺少内部文本，则显示默认的警告文本: “[此文档为预发布版本，在未来版本中有可能改变。]”。

如果需要把全部类型/成员都标记为“预发布”，请使用文档引擎的 Preliminary 配置项。

<remarks>

“备注”，对 <summary> 的进一步注解。

<returns>

“返回值”。

<seealso>

向页面的“请参见”区域添加一个链接。

请不要将此标记包含在 <remarks> 内部，它是一个顶级标记。

两种可选的语法:

· <seealso href="http://www.microsoft.com/china/msdn/">MSDN(CHS)</seealso>

· <seealso cref="System.Data.DataSet">DataSet</seealso>

<summary>

“摘要”，对类型/成员的摘要说明。

<threadsafety>

[NDoc 扩充]

“线程安全”，说明类型在多线程环境中是否安全。

NDoc 提供 static 和 instance 两个布尔的属性，可以自动生成像 .NET Framework SDK 类库文档中那样的标准文本。

threadsafety 标记内部可以包含额外的文本，会被显示到标准文本的下方，说明额外的信息。例如:

/// <summary>The summary description for SafeClass.</summary>

/// <threadsafety static="true" instance="true">

///    <para>More information about using this class across thread</para>

/// </threadsafety>

public class SafeClass() { ... }

<value>

“属性值”。

Block 标记

Block 标记用于 Section 标记的内部，它们将显示在单独的行中。

标记

说明

<code>

多行的代码块。

<list>

一个列表或表格。

<note>

[NDoc 扩充]

“注意”块。

例如:

/// <summary>

/// <note>This is a note in the summary.</note>

/// </summary>

public class SomeClass() { ... }

将生成:

注意 This is a note in the summary.

<para>

表示一个段落。

Inline 标记

Inline 标记可以用于其他 Section 标记或 Block 标记内部，它们将和前后的文本显示在同一行中。

标记

说明

<c>

将内部文本格式化为代码样式，用于表示行文中提到的短小代码片段。

<paramref>

加入指向方法参数的链接。

<see>

加入指向某个类型/成员或网络 URL 的链接。

两种可选的语法:

· <see href="http://www.microsoft.com/china/msdn/">MSDN(CHS)</see>

· <see cref="System.Data.DataSet">DataSet</see>

· <see langword="xxx"/>
其中 xxx 可以是 null, sealed, static, abstract 或 virtual。

第三步：就是使用我们的NDoc工具了

如果您使用 Visual Studio.NET 开发工具，那么最简单的方法就是点击工具条中的“从 Visual Studio .NET 解决方案新建 NDoc 项目...”按钮。

然后，NDoc 会要求您选择某种编译配置(如 Debug 或 Release，或者其他您自定义的编译配置)，这取决于您将使用哪种编译配置下生成的程序集和 XML 文档。

编译配置选择对话框

“确定”之后，NDoc 项目设计器将自动生成一个新的 NDoc 项目，其中已包含解决方案中各个项目生成的程序集和相应的 XML 文档。

如果您没有使用 Visual Studio .NET，则需要手工向 NDoc 项目添加要生成代码文档的程序集和相应的 XML 文档。您可以通过点击设计器重的“添加”按钮、从文件系统中浏览并选择要添加的程序集，也可以直接从 Windows 资源管理器或“我的电脑”中、直接拖动要生成代码文档的程序集、到设计器中的程序集列表框中。

请确保您打开了 /doc 文档输出的选项，否则 NDoc 输出的代码文档只能有很少的内容。选择文档引擎

NDoc 内置了若干文档引擎，它们可以用于生成不同风格、样式、格式的代码文档。每种文档引擎都定义了它自己的排版、格式，以及要输出的内容。

最受欢迎的两种文档引擎是 MSDN 和 VS.NET 2003。它们都生成类似 .NET Framework SDK 类库文档样式的代码文档，不同的是前者最终编译成 HTML Help 1 （即 *.CHM）格式的整合文件，后者最终编译成 Microsoft Help 2 (即以形如 ms-help://... 的 URI 地址访问的文档)格式的形式。

NDoc 1.3 中，新增了 MSDN 2003 文档引擎，在保留 MSDN 文档引擎的特点之外，向接近 .NET Framework SDK 类库文档的方向又前进了一大步：加入了语言选择器等特色功能。

NDoc 文档引擎

所有的文档引擎都共享一些配置项，比如要输出哪些类型/不输出哪些类型等；每种文档引擎都会有一些额外的配置项，用于特定的配置。

这里还有要说的就是这些文档引擎，需要安装相应的支持工具

HTML Help 1 编译器

HTML Help 1 文件，也就是 CHM 文件，是很常见的应用程序帮助文件格式，在 Visual Studio .NET 发布之前，MSDN 一直采用的就是 HTML Help 1 格式。

如果您准备创建 HTML Help 1 (*.CHM)文件，请确认您已经安装好 Microsoft's HTML Help Workshop。此下载安装包已包含必需的 HTML Help 1 编译器。

Microsoft Help 2 编译器

Microsoft Help 2 是 Microsoft 从 Visual Studio .NET 2002 开始使用的、一种新的帮助文档格式。

如果您准备创建 Microsoft Help 2 (*.HxS)文件，请下载并安装 Visual Studio Help Integration Kit (VSHIK)。此工具包已包含所必需的 Microsoft Help 2 编译器。

Latex 编译器

如果您准备使用 LaTeX 文档引擎创建 dvi 或 pdf 文件，您需要下载并安装一个 LaTeX 系统，比如免费的 MikTeX。

生成代码文档

选择好文档引擎，并做好相应的配置。您就可以点击“生成”按钮让 NDoc 创建您需要的代码文档了。设计器下方的“输出”窗口中将显示文档制作中的消息，状态条上的进度条指示生成的整体进度。

NDoc 生成进度

查看文档 生成成功后，您可以点击“查看文档”按钮查看生成的代码文档。

最后，希望大家用好这个小工具，让我们的程序代码更有价值。

转载于:https://www.cnblogs.com/jht/archive/2005/10/21/258805.html

NDoc –NET 代码文档生成器快速度上手相关推荐

  1. vue 插入word模板 项目_10 分钟为你的 vue 项目编写代码文档

    代码文档是软件开发使用和维护的必备资料,有了文档,开发和维护以及协作的效率将变得大大提升.tips:如果对 JSDoc 已经熟悉,可以直接跳到实战演练环节. 什么是文档?软件文档或者源代码文档是指与软 ...

  2. 代码文档生成工具-Doxygen生成CHM和RTF图文教程

    Doxygen是一种开源跨平台的,以类似JavaDoc风格描述的文档系统,可以从一套归档源文件开始,生成chm格式的文档.本文主要讲解如何在winddows下安装doxygen. 1.下载doxyge ...

  3. 不给代码写文档，让代码文档化

    这是程序员讨论了很久的一个话题:要不要给代码写文档?值得给代码写文档吗? 我曾经觉得这个话题实在是让人难以应付.也认为除去一些特殊的情况(比如编写公用 API),代码文档并不是那么必要.直到有一天,我 ...

  4. Python+Streamlit aggrid+MongoDB GridFS构建低代码文档管理应用（文档查询下载实用篇）

    1. Sreamlit aggrid简介 Sreamlit aggrid是Streamlit的Ag-Grid组件的实现,在Python Streamlit框架下,更加灵活的使用表格,包括分组.排序.编 ...

  5. 火车车次查询api代码文档及返回示例分享

    火车车次查询api代码文档及返回示例分享,支持出发站名称.到达站名称.车次类型等查询,将其集中到APP中,使用更加方便. 接口名称:火车车次查询api 接口平台:api接口 接口地址:http://a ...

  6. 开源免费,又一款代码文档生成工具

    原文链接:https://gitee.com/sharetech_lee/DevWeekly DevWeekly收集整理每周优质开发者内容,包括开源项目.资源工具.技术文章等方面. 每周五定期发布,同 ...

  7. 开发者神器，代码文档终于有救了

    程序员宝藏库:你想要的,应有尽有! DevWeekly收集整理每周优质开发者内容,包括开源项目.资源工具.技术文章等方面. 每周五定期发布,同步更新到知乎:Jackpop 和公众号:平凡而诗意 . 欢 ...

  8. 『原创』教你如何使用Sandcastle Help File Builder建立MSDN风格的代码文档

    今天在公司特别研究了Sandcastle.NDoc以及Sandcastle Help File Builder(以下简称SHFB)的使用,发现还是SFHB好用,特在此写下一篇供大家参考(毕竟那个界面是 ...

  9. dw的html代码文档,Dw 基础篇：DW的文档工具栏

    以下选项出现在"文档"工具栏中: 服务器调试显示一个报告,帮助您调试当前 ColdFusion 页.该报告包括您的页面中的错误(如果有的话). 文档标题允许您为文档输入一个标题,它 ...

最新文章

  1. 定时任务 Cron表达式
  2. python入门教程书籍-初学者最好的Python书籍
  3. ffmpeg库编译加文字_ffmpeg第三方库编译记录
  4. Delphi 字符串转十六进制
  5. php object oriented,PHP学习记录之面向对象（Object-oriented programming，OOP）基础【接口、抽象类、静态方法等】...
  6. 技术动态 | 知识可视化，连接和探究知识之间的联系！
  7. Word中MathType公式与LaTeX公式的转换
  8. 微积分基础1-微分篇
  9. Navicat Premium 12.0.29 / 12.1.5.0注册机激活
  10. SpringMVC 访问html页面乱码
  11. java基于for、while循环经典案例题（仅供参考）
  12. 路由器配置 IP 地址
  13. C# 打开和关闭软键盘
  14. 使用gcc参数-Wl,–gc-sections，不链接未用函数，减小可执行文件大小
  15. matlab书籍（数学建模，信号处理，智能优化，统计分析）
  16. Zeppelin上通过Spark读写mysql数据库
  17. Adobe Photoshop 2022新版本下载体验，看看“新”在哪？
  18. java实现支付宝支付及退款（二）
  19. python利用WPS接口之excel中图片写入
  20. 逆向工程如何进行sql语句的查询

热门文章

  1. java制表位是什么意思_java制表位如何应用？大神进来。
  2. 【RocketMQ工作原理】消息的生产过程
  3. 想转行软件测试，简历怎么包装成1年工作经验的测试工程师
  4. 想学测试如何入门和学习软件测试？今天我就好好给你唠唠
  5. 哇塞，可以使用PyTorch实现目标检测与跟踪，这不有趣多了
  6. 多模态理论张德禄_观点 | 多模态研究：认知语言学的新方法
  7. 堆排序怎么建立初始堆_学习笔记-详解堆排序
  8. 看漫画学python 豆瓣_漫画，小莉要学Python后端，看大牛是怎么教她的！
  9. 大学学了java可以做点什么_学习Java的,大学毕业一般从事些什么工作?
  10. 扩展源_Ubuntu14版本下无法使用php7.2版本的bcmath扩展