扫一扫
分享文章到微信
扫一扫
关注官方公众号
至顶头条
作者:中国IT实验室 来源:中国IT实验室 2007年9月30日
关键字: Sandcastle 微软 编程
从一开始,.NET Framework就允许C#开发者在他们的代码中使用XML形式的注释。这一特性被增加到VB.NET 2.0中。该编译器能够使用这些注释生成基本的技术文档。使用XML注释最终得到一个难以理解的大型XML文件。
开发者想要并希望用其它工具代替XML,建立更易于理解的文档。开源项目NDoc通过改进和简化上述过程,并提供各种帮助文件格式,满足了这一需求。遗憾的是,由于创立者很少或几乎没有得到开发社区的支持,最终该项目被终止。
NDoc宣布终止后,微软推出它的第一版文档工具――Sandcastle。这是一个管理类库的文档编译器。它还可通过反射处理汇编源代码,并在代码中使用XML注释生成MSDN形式的文档,这种文档比难以解读的XML更易于理解。微软称它在内部使用它创建.NET Framework文档。
Sandcastle与.NET Framework 2.0(可在线找到它与1.1版本的用法说明)和.NET Compact Framework组合使用。Sandcastle支持本地化,并提供一个基本的命令行编译器界面和一个Visual Studio插件。
如何获取Sandcastle
微软2007年3月的社区技术预览提供最新版的Sandcastle。你可以在Windows Server 2003或Windows XP Service Pack 2上安装和运行该工具。它需要系统上安装有.NET Framework 2.0和HTML Help Workshop。安装必要的软件后,你就可以接着安装Sandcastle工具。
深入了解
Sandcastle中共有三个组件:MrefBuilder、Build Assembler和XslTransform。这些工具使用编译汇编代码时生成的输出结果,包括DLL文件以及XML注释文件。
MrefBuilder反射一个项目的汇编代码并生成一个输出文件。MrefBuilder是一个随Sandcastle安装的命令行工具。它生成的输出文件通过XslTransform命令行工具转换成一个叫做reflection.xml的文件。reflection.xml文件包含所有文档数据,但不提供显示细节。
MrefBuilder完成工作后,立即由Build Assembler接手处理。Build Assembler可由命令行工具BuildAssembler启动。它利用由MrefBuilder生成的数据(reflection.xml)和任何代码注释(保存在独立的XML文件中),生成按逻辑分组的HTML文件。HTML Help Compiler再利用这些HTML文件生成最终结果。
该工具并未限制你一次处理一个汇编。如果你需要处理几个汇编代码,你必须深入了解Sandcastle配置文件。它是一个包含建立帮助文件主题所需步骤的XML文件。
输出结果
Sandcastle生成的输出结果具有以下特点:
输出结果以HTML和CSS形式显示,微软承诺将来提供更多选择。
可选界面
许多开发者讨厌命令行界面――他们更喜欢灵巧的GUI界面,如流行的Visual Studio IDE。同时,你还可以使用第三方工具,利用一个友好的GUI界面推动Sandcastle过程。以下是三个有效的工具:
帮助他人
如果开发者处理应用程序代码,他们需要了解应用程序的工作原理,以及如何使用应用程序界面。微软Sandcastle提供为你的项目生成MSDN形式文档所需的必要工具。检查这个Sandcastle wiki了解该工具。
你一直都对代码归档吗?在开发文档时你使用哪些工具和技巧?请在文后的讨论部分与社区分享你的观点和经历。
婵犵數濮烽。浠嬪焵椤掆偓閸熷潡鍩€椤掆偓缂嶅﹪骞冨Ο璇茬窞闁归偊鍓涢悾娲⒑闂堟单鍫ュ疾濠婂嫭鍙忔繝濠傜墛閸嬨劍銇勯弽銊с€掗柟钘夊暣閺岀喖鎮滈埡鍌涚彋閻庤娲樺畝绋跨暦閸洖鐓涢柛灞剧矋濞堟悂姊绘担绛嬪殐闁搞劋鍗冲畷銏ゅ冀椤愩儱小闂佹寧绋戠€氼參宕伴崱妯镐簻闁靛牆鎳庢慨顒€鈹戦埥鍡椾簼婵犮垺锚铻炴俊銈呮噺閸嬪倹绻涢崱妯诲碍閻庢艾顦甸弻宥堫檨闁告挾鍠庨锝夘敆娓氬﹦鐭楁繛鎾村焹閸嬫捇鏌e☉娆愬磳闁哄本绋戦埞鎴﹀川椤曞懏鈻婄紓鍌欑劍椤ㄥ懘鎯岄崒鐐靛祦閹兼番鍔岄悞鍨亜閹烘垵顏╅悗姘槹閵囧嫰寮介妸褎鍣ョ紓浣筋嚙濡繈寮婚悢纰辨晣鐟滃秹鎮橀懠顒傜<閺夊牄鍔庣粻鐐烘煛鐏炶姤鍠橀柡浣瑰姍瀹曠喖顢橀悩铏钒闂備浇宕垫慨鎶芥⒔瀹ュ鍨傞柦妯猴級閿濆绀嬫い鏍ㄧ☉濞堟粓姊虹涵鍛【妞ゎ偅娲熼崺鈧い鎺嗗亾闁挎洩濡囧Σ鎰板籍閸繄顓洪梺缁樺姇瀵剙螖閸涱喚鍘搁梺鍓插亽閸嬪嫰鎮橀敃鍌涚厱閻庯綆鍋嗘晶顒傜磼閸屾稑绗ч柟鐟板閹煎湱鎲撮崟闈涙櫏闂傚倷绀侀幖顐も偓姘卞厴瀹曞綊鏌嗗鍛紱閻庡箍鍎遍ˇ浼村磿瀹ュ鐓曢柡鍥ュ妼婢ь垰霉閻樿秮顏堟箒闂佹寧绻傚Λ妤呭煝閺囥垺鐓冪憸婊堝礈濮樿泛钃熼柕濞у嫷鍋ㄩ梺缁樺姇椤曨參鍩㈤弴銏″€甸柨婵嗗€瑰▍鍥ㄣ亜韫囨稐鎲鹃柡灞炬礋瀹曢亶顢橀悢濂変紦