NDoc: How to Make Good Use of Your XML Comments?

Written by Allen Lee

Requirement

  • 使用C#进行库的开发。
  • 在源代码里使用XML注释。
  • 厌倦额外的文档编制工作,希望有无怨无悔的电脑接手这份枯燥无味的工作。
  • 具备C#的开发条件,至少需要.NET Framework SDK 1.1。
  • 能尽量抑制你的瞌睡虫,不让它阻碍你阅读本文。
  • 其它...

Encountered Problems

  • 面向对象技术的普及,为我们带来了极大的便利。对象的重用减轻了我们编码时许多不必要的痛苦,清晰的代码责任分离制免除了我们每顿都要面对着“意大利粉”的厌恶。
  • 但是,我们仍然要面对着枯燥的文档编制——从内容构思到页面排版。相信库开发人员对这种厌恶已经深有感触,即使我们都承认文档的重要性。 当然,某些大企业有专人写文档,但最了解库的却是程序员自己!而程序员往往又会在自己开发的库中为代码添加注释,如果有个工具能够利用这些注释按照一定的格式要求直接导出文档该多好呀!
  • 聪明而“懒惰”的程序员总是比其他人先行一步,他们不愿把自己放进重复而枯燥的方框内,他们千方百计要跳出这个方框,让自己能够从事更富创造性的活动,把这些枯燥无味的扔给无怨无悔的电脑们。

Feel Free to Write Your Class Library With XML Comments Added

  • 单纯的文字无法让你领略NDoc的魅力,至少我还没有这个能力。睡着了吗?(或许周公的故事更加有趣!)还没有的话请看看下面这段示范代码——一个表示复数的类(class)。
using System;
using System.Globalization;

namespace MathUtils
{
    /**//// <summary>
    /// 提供复数的相关操作服务。
    /// </summary>
    public sealed class Complex
    {
        /**//// <summary>
        /// 默认构造器,将复数的实部与虚部分别设置为0;
        /// </summary>
        public Complex()
        {
            _Real = 0;
            _Imaginary = 0;
        }

        /**//// <summary>
        /// 分别将复数的实部与虚部设置为指定的值。
        /// </summary>
        /// <param name="real"></param>
        /// <param name="imaginary"></param>
        public Complex(int real, int imaginary)
        {
            _Real = real;
            _Imaginary = imaginary;
        }

        private int _Real;
        /**//// <summary>
        /// 复数的实部。
        /// </summary>
        public int Real
        {
            get
            {
                return _Real;
            }
            set
            {
                _Real = value;
            }
        }

        private int _Imaginary;
        /**//// <summary>
        /// 复数的虚部。
        /// </summary>
        public int Imaginary
        {
            get
            {
                return _Imaginary;
            }
            set
            {
                _Imaginary = value;
            }
        }

        /**//// <summary>
        /// 把复数转换为对应的字符串形式。
        /// </summary>
        /// <returns>
        /// 返回(X)+(Y)i的形式的字符串。
        /// </returns>
        public override string ToString()
        {
            return String.Format(CultureInfo.InvariantCulture,
            "{0} + {1}i",
            _Real,
            _Imaginary);
        }

    }
}

Generate Your XML Comments to A Seperate XML File

  • 如果你有Visual C# .NET,那么你可以轻松的使用一下的步骤:在解决方案管理器中右键单击该项目图标,依次选择 属性 | 配置属性 | 生成,在 [输出] 的 [XML 文档文件] 右边填入目标XML文件的文件名,这里是Complex.xml。保存设置并关闭该对话框,生成该项目,你将会在项目的根目录中找到这个XML文件。

  • 没有Visual C# .NET?没所谓,用C#的命令行编译器CSC.exe也可以。只需要在源代码所在的目录的命令提示符下键入csc /t:library /doc:Complex.xml Complex.cs<Enter>(详细请参见下面的评论),就可以生成XML注释文件了。
  • 好了,现在来看看我们第一阶段的劳动成果:
<?xml version="1.0" encoding="utf-8" ?> 
<doc>
    <assembly>
        <name>Complex</name>
    </assembly>
    <members>
        <member name="T:MathUtils.Complex">
            <summary>
            提供复数的相关操作服务。
            </summary>
        </member>
        <member name="M:MathUtils.Complex.#ctor">
            <summary>
            默认构造器,将复数的实部与虚部分别设置为0;
            </summary>
        </member>
        <member name="M:MathUtils.Complex.#ctor(System.Int32,System.Int32)">
            <summary>
            分别将复数的实部与虚部设置为指定的值。
            </summary>
            <param name="real"></param>
            <param name="imaginary"></param>
        </member>
        <member name="M:MathUtils.Complex.ToString">
            <summary>
            把复数转换为对应的字符串形式。
            </summary>
            <returns>
            返回(X)+(Y)i的形式的字符串。
            </returns>
        </member>
        <member name="P:MathUtils.Complex.Real">
            <summary>
            复数的实部。
            </summary>
        </member>
        <member name="P:MathUtils.Complex.Imaginary">
            <summary>
            复数的虚部。
            </summary>
        </member>
    </members>
</doc>

Where Is Our Protagonist?

  • 现在是时候轮到这出戏的主角出场了——NDoc。接下来...下载...安装...启动NDoc...(是否人类总不能摆脱枯燥无味呢?)按下 [Add] 来添加你的Dll或Exe,以及与之相关联的XML注释文件。

  • 你希望NDoc用什么样的格式来生成库文档呢?哟,可供选择的类型也不少嘛!我们试试MSDN吧!

  • 好了,万事俱备,只欠生成。Now build it!

  • Well done! 这就是我们的第二阶段成果,也就是最终成果了!有没有觉得手痒想试一下呢?

Conclusion

  • 终于大结局啦,一百个人就有一百个哈姆雷特,不知道NDoc在你心目中是怎么一个形象呢?
  • 不知道你是否认为NDoc偏心,只对能使用XML Comments的C#这么好。然而,VB.NET也不需要感到难过,因为你有个VBCommenter在背后默默的支持你呢!

转载于:https://www.cnblogs.com/allenlooplee/archive/2004/10/24/56181.html

NDoc: How to Make Good Use of Your XML Comments?相关推荐

  1. .net的辅助工具列表

    .net的辅助工具列表: Code generation NVelocity CodeSmith X-Code .NET XGoF - NMatrix / DEVerest Compilation e ...

  2. NDoc –NET 代码文档生成器快速度上手

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

  3. [转]Sandcastle初探——官方版的NDoc

    Sandcastle初探--官方版的NDoc Sandcastle(CodeName)是微软出的用于编译发布组件(Assembly)信息的一个工具,基本上等同于NDoc(后者目前已经停止开发,最新版本 ...

  4. .NET开发系列工具之NDoc:让NDoc支持简体中文!(含修改了的源代码)

    关于NDoc,无论是在博客园还是其它技术网站,都有大量的介绍,这里不介绍其功能(除非有大量网友要求我这样做),只给大家实现其对简体中文的支持. NDoc缺省不支持简体中文,编译出来的chm文档(MSD ...

  5. NDoc修改版,支持中文注释及中文界面。

    这几天正在做一个项目的开发文档,以前试用NDoc做开发文档时不支持中文,真是不爽.这几天看了源代码,修改了其中的一段源代码及配置文件后,支持中文注释及中文界面(目前只做了Msdn2003一种). 以下 ...

  6. 在Vs.net中集成 NDoc生成的 Html Help 2帮助文档

    注:NDoc是一个Open Source的For .Net 文档自动生成软件.它可以通过 .Net中XML的注释标签来生成非常漂亮的MSDN风格的类库文档.(相对于VS.Net自己带的Comment ...

  7. NDoc使用简要手册的补充

    感谢Jam Snake在NDoc使用简要手册中的评论 NDoc中的一些参数设置可以控制生成显示,如下图: 将DocumentPrivates打开则可以显示private的方法了.

  8. NDoc修改手记(一)

    NDoc是一个非常不错的C#文档生成工具,但在使用的过程中发现在用其生成的Msdn类文档使用LangID为2052--也就是使用简体中文时,空格被?代替了,怎样解决它呢? 一个偶然的机会看到了这里ht ...

  9. NDoc使用简要手册 及中文支持(转)

    NDoc使用简要手册 http://www.cnblogs.com/windsails/articles/40212.html NDoc中文支持 http://www.cnblogs.com/keyb ...

  10. VS2010 NDoc的插件工具

    1.下载Sandcastle Help File Builder: http://www.codeplex.com/SHFB 2.下载sandcastle: http://www.microsoft. ...

最新文章

  1. push_back()和emplace_back()函数
  2. php分享十五:php的数据库操作
  3. 认识学习网络布线与数制转换
  4. SFB 项目经验-02-共存迁移-Lync 2013-TO-SFB 2015-规划02
  5. ASP.NET Core中如何调整HTTP请求大小的几种方式
  6. poj-2528线段树练习
  7. 一步步带你实现简版 ButterKnife
  8. java 路由_RabbitMQ入门:路由(Routing)
  9. [开源] 使用 Python 轻松操作已存在的表
  10. 二相漏电断路器接线图_怎么看配电柜接线图?配电柜接线图读图技巧
  11. 绿盟安全扫描--检测到目标站点存在javascript框架库漏洞
  12. Java使用POI实现多个excel合并成一个excel
  13. metasploit、msfvenom生成木马入侵电脑及手机
  14. 计算机专业大学生怎么学习?
  15. 运动型蓝牙耳机什么牌子好、最适合运动的耳机
  16. 山东大学青岛校区,拟筹建工业互联网国家重点实验室!
  17. 通过溢出码解锁电脑BIOS密码
  18. 传感器实验——控制电机
  19. 栅格地图中自由区域之Bresenham算法及个人搜索算法对比
  20. python实现图数据结构_Python描述数据结构之图实战篇

热门文章

  1. Struts2检测工具
  2. nodejs 项目目录结构设计
  3. 将Python程序打包成exe文件
  4. 不花钱也能使用迅雷的高速通…
  5. 2进制原码反码补码,2进制加减乘除原理
  6. Python报错:ImportError: cannot import name 'downsample'
  7. 2019-08-27-Seo基础知识
  8. 苹果手表连接是什么原理_为什么苹果手表是最具潜力的苹果产品
  9. mysql用户域账户登录_使用本地系统帐户和域用户帐户两者区别(microsoft SQLServer2000...
  10. java der格式_读取DER格式java中的私钥