.net中的自动文档生成工具

由于项目的原因，我需要使用C#编程，以前使用JAVA的时候，就觉得javadoc是非常方便的功能，C#里面也添加了对xml格式的注释的支持，我想当然的觉得Visul Studio里面也会带有类似javadoc那样的工具简简单单就可以生成不差于javadoc的文档。

实际上，我大错特错了。我用的是VS2005，里面根本就没有找到类似的选项，最多只能生成一个xml格式的注释提取文件，但是大家都知道，xml虽然是文档，但是not for humen beings。通过搜索，我知道了早在.net 2003的时期，VS是支持这个功能的，但是从2005开始，这个功能就被取消掉了。

一般网上搜索到的文章都会推荐NDoc1.3，这个着实误导了我一会儿，因为这个叫NDoc的开源项目早在2005年就已经停止开发了。其支持的.net framework版本只达到1.1。关于介绍这个NDoc的使用的文章，大家可以看一篇英文的文档如下：

http://www.codeproject.com/KB/XML/csharpcodedocumentation.aspx

上述文档从C#中的xml格式的注释开始，到NDoc的使用，都给出了非常详尽的说明。但是，现在真的还有人用.net 1.1的话，看到这里就可以直接去留言了，呵呵。我现在正在使用的是.net 2.0，我相信还有很多人跟我用同样的版本。刚才提到的NDoc最终版本为1.3，不支持.net 2.0，那么下面这篇文档介绍了如何让NDoc 1.3支持.net 2.0，一共给出了三种方法。

http://forums.asp.net/t/997774.aspx

不过，我都没有实验成功，一个是通过改配置文件的方法，上面的帖子里面可以下载的。还有一个是通过重新用VS2005编译NDoc1.3的源码的方法，这个方法在转换项目的时候有一个链接库找不到，是Html Help Workshop的一个链接库，我的系统里面没有，所以我这个方法也没有成功。

再后来，我找到了微软官方发布的工具，叫做Sandcastle（沙堡？），这个工具是微软官方推出的专门用来生成文档的工具，不过很遗憾是命令行工具，当然我不是一个命令行狂热者，否则我不会这么失望。下面的链接给出了这个工具的博客，可能你会找不到下载链接，呵呵:-)。

http://blogs.msdn.com/sandcastle/

上面的那个官方的，王道的工具，真的很难用，我装上了，完全用不了，因为要好几个步骤，好多命令，所以，骂我白痴吧。但是有个好心的老外，为其开发了一个界面，叫做SandcastleGUI，就是很简单的界面，在下面的页面里，大家可以看到这个工具的介绍。

http://www.inchl.nl/SandcastleGUI/

http://www.codeproject.com/KB/cs/SandcastleBuilder.aspx

经过试用，我发现，这个东西似乎没有什么作用，就是基本上什么也没有产生出来，所以，真的让我很失望，但是很多人说这个挺好用，第二个链接是另一个GUI的Sandcastle，界面模仿得已经和NDoc很像了，但是我用了以后，发现我程序里面引用了一个第三方插件，造成这个东西异常了，最终也没有能够产生出我要的文档。看来微软的这个工具还真的像沙塔一样不可靠呢。

最后，我知道了一个叫做NDoc2005的开源项目，在NDoc的基础上建立起来的，可以兼容.net 2.0。看来，我的希望来了。

http://sourceforge.net/projects/ndoc05

上面的网址可以获取NDoc 2005版本，但是我提醒想要偷懒的兄弟们，一定要下载源代码包，因为如果你只下载安装包的话，你会发现有个叫做Documenter的东西一直找不到，你什么文档都得不到的，只有那个src包里面才有这个文件夹。我就是把这个文件夹拷贝到了C:\Document and Settings\下面，才能正常使用的。这个工具如同NDoc1.3，可以生成msdn，xml，javadoc，msdn2003（beta）等各种格式的文档。非常强大。而且，如果程序里面引用了第三方插件的话，也可以成功跨过去，编译第一次会失败，第二次就会成功（不知道为什么）。

本来，故事到这里就结束了。但是，如果你像我一样，非常土的用中文写注释的话，那么故事还没有完，有可能你会碰到这个情况。当你编译msdn格式的文档的时候，你把LangID选成2052的时候，虽然能够支持中文，但是英文空格都以"？"来显示，而你把LangID选成1033的时候，虽然英文正常，但是所有汉字都是"？"，怎么样，够恶心吧，不能非得二选一吧，我甚至尝试着自己编译NDoc2005的源代码，解决问题失败。

终于，皇天不负有心人，我找到了这个。NDoc2007，实际上那篇文章是非常简单的，就给了个链接和一句话。见下面的链接。

http://blog.vckbase.com/bastet/archive/2007/07/11/27300.html

如果那个链接已经失效了，我还备份了一份。点这里。