生成帮助文件软件选择
如要想与VS集成在一起，可以使用
（1）Sandcastle Help File Builder /
（2）DocProject /
（3）GhostDoc /products/ghostdoc.aspx
如果不用与VS集成在一起，可以使用
（1）Doxygen http://www.stack.nl/~dimitri/doxygen/
（2）Docu /
（3）NDoc3 /projects/ndoc3/
Sandcastle的使用
介绍
Sancastle由微软创建于，软件包含两部分：Sandcastle tools和Sandcastle Help File Builder。
Sandcastle tools用于为管理的类库创建帮助文件，帮助文件中含有概念的和API引用主题，API引用主题由嵌入在源码中的XML部分生成，概念性主题由MAML编写的XML文件生成。Sandcastle tools基于命令行，没有GUI界面，没有工程管理特性，没有自动生成处理功能。
Sandcastle Help File Builder提供了GUI界面用于与Sandcastle tools交互，另外也提供了一个Visual Studio集成的包，用于Visual Studio帮助文档的创建。
安装
下载最近版本的Sandcastle，运行SandcastleInstaller.exe，然后按着提示一步步安装。
为了使用help file builder,需要用到下的工具，不同工具用于生成不同类型的帮助文件：
（1）生成chm类型的帮助文档，需要HTML Help Workshop ,下载地址：/en-us/library/ms669985.aspx
使用
为了创建帮助文件，需要开启Visual Studio工程的“XML注释文件生成”。
（1）在解决方案浏览器中，右键工程选择“属性”
（2）选择“生成”属性一页
（3）在“输出”一节中，勾选“xml文档文件”，名称不是必须的，一般是程序集的名称+xml后缀，程序集名称可以在“应用程序”属性页中找到。
（4）如果解决方案中有多个工程，对每个工程重复（1）~（3）
对于托管的C++工程，需要的下面的步骤：
（1）在解决方案浏览器中，右键工程选择“属性”
（2）展开“Configuration Properties”分类，然后展开“c/c++”子分类，选择下面的“Output Files”选项。
（3）在“Output Files”选项中，把“Generate XML Documentation Files”选项设为Yes
（4）如果你想改变xml文件的名称，选择“XML Docuemnt Generator”分类下的“Configuration Propertiers”子分类中“Output Document File”属性改变名称。
（5）如果解决方案中有很多工程，重复（1）~（4）
XML格式的注释都是单行注释，都以3个斜杠（///）开头。可以参考：/zh-cn/library/b2s063f7.aspx
示例说明：
<c>text</c>
// compile with: /doc:DocFileName.xml /// text for class TestClasspublic class TestClass{/// <summary><c>DoWork</c> is a method in the <c>TestClass</c> class./// </summary>public static void DoWork(int Int1){}/// text for Mainstatic void Main(){}}
// Save this file as CRefTest.cs// Compile with: csc CRefTest.cs /doc:Results.xml namespace TestNamespace{/// <summary>/// TestClass contains several cref examples./// </summary>public class TestClass{/// <summary>/// This sample shows how to specify the <see cref="TestClass"/> constructor as a cref attribute./// </summary>public TestClass(){ }/// <summary>/// This sample shows how to specify the <see cref="TestClass(int)"/> constructor as a cref attribute./// </summary>public TestClass(int value){ }/// <summary>/// The GetZero method./// </summary>/// <example> /// This sample shows how to call the <see cref="GetZero"/> method./// <code>/// class TestClass /// {///static int Main() ///{/// return GetZero();///}/// }/// </code>/// </example>public static int GetZero(){return 0;}/// <summary>/// The GetGenericValue method./// </summary>/// <remarks> /// This sample shows how to specify the <see cref="GetGenericValue"/> method as a cref attribute./// </remarks>public static T GetGenericValue<T>(T para){return para;}}/// <summary>/// GenericClass./// </summary>/// <remarks> /// This example shows how to specify the <see cref="GenericClass{T}"/> type as a cref attribute./// </remarks>class GenericClass<T>{// Fields and members.}class Program{static int Main(){return TestClass.GetZero();}}}
<exception cref="member">destription</exception>
cref = "member"
对可从当前编译环境中获取的异常的引用。编译器检查到给定异常存在后，将member转换为输出 XML 中的规范化元素名称。member必须位于双引号 (" ") 中。
/// Comment for classpublic class EClass : System.Exception{// class definition...}/// Comment for classclass TestClass{/// <exception cref="System.Exception">Thrown when...</exception>public void DoSomething(){try{}catch (EClass){}}}
<include file='filename' path='tagpath[@name="id"]' />
filename
包含文档的 XML 文件的名称。该文件名可用路径加以限定。将filename括在单引号 (' ') 中。
tagpath
filename中指向标记name的标记路径。将此路径括在单引号中 (' ')。
name
注释前边的标记中的名称说明符；name具有一个id。
id
位于注释之前的标记的 ID。将此 ID 括在双引号中 (" ")。
/// <include file='xml_include_tag.doc' path='MyDocs/MyMembers[@name="test"]/*' />class Test{static void Main(){}}/// <include file='xml_include_tag.doc' path='MyDocs/MyMembers[@name="test2"]/*' />class Test2{public void Test(){}}
xml_include_tag.doc
<pre name="code" class="csharp"><pre name="code" class="html"><MyDocs><MyMembers name="test"><summary>The summary for this type.</summary></MyMembers><MyMembers name="test2"><summary>The summary for this other type.</summary></MyMembers></MyDocs>
<list type="bullet" | "number" | "table"><listheader><term>term</term><description>description</description></listheader><item><term>term</term><description>description</description></item></list>
term
要定义的项，该项将在description中定义。
description
项目符号列表或编号列表中的项或者term的定义。
/// text for class TestClass public class TestClass { /// <summary>Here is an example of a bulleted list: /// <list type="bullet"> /// <item> /// <description>Item 1.</description> /// </item> /// <item> /// <description>Item 2.</description> /// </item> /// </list> /// </summary> static void Main() { } }
<para>content</para>
<para> 标记用于诸如<summary>、<remarks>或<returns>等标记内
<param name="name">description</param>
<param> 标记应当用于方法声明的注释中，以描述方法的一个参数。如要记录多个参数，请使用多个 <param> 标记。
<paramref name="name"/>
<paramref> 标记提供了指示代码注释中的某个单词（例如在 <summary> 或 <remarks> 块中）引用某个参数的方式。可以处理 XML 文件来以不同的方式格式化此单词，比如将其设置为粗体或斜体。
/// text for class TestClass public class TestClass { /// <summary>DoWork is a method in the TestClass class. /// The <paramref name="Int1"/> parameter takes a number. /// </summary> public static void DoWork(int Int1) { } /// text for Main static void Main() { } }
<permission cref="member">description</permission>
<permission> 标记使您得以将成员的访问记入文档。使用PermissionSet类可以指定对成员的访问。
class TestClass { /// <permission cref="System.Security.PermissionSet">Everyone can access this method.</permission> public static void Test() { } static void Main() { } }
/// <summary> /// You may have some primary information about this class. /// </summary> /// <remarks> /// You may have some additional information about this class. /// </remarks> public class TestClass { /// text for Main static void Main() { } }
/// text for class TestClass public class TestClass { /// <returns>Returns zero.</returns> public static int GetZero() { return 0; } /// text for Main static void Main() { } }
<see cref="member" />
<see> 标记使您得以从文本内指定链接。使用<seealso>指示文本应该放在“另请参见”节中。用cref 特性创建指向代码元素的文档页内部超链接。
/// text for class TestClass public class TestClass { /// <summary>DoWork is a method in the TestClass class. /// <para>Here's how you could make a second paragraph in a description. <see cref="System.Console.WriteLine(System.String)"/> for information about output statements.</para> /// <seealso cref="TestClass.Main"/> /// </summary> public static void DoWork(int Int1) { } /// text for Main static void Main() { } }
<typeparam name="name">description</typeparam
/// comment for class public class TestClass { /// <summary> /// Creates a new array of arbitrary type <typeparamref name="T"/> /// </summary> /// <typeparam name="T">The element type of the array</typeparam> public static T[] mkArray<T>(int n) { return new T[n]; } }
/// text for class Employee public class Employee { private string _name; /// <summary>The Name property represents the employee's name.</summary> /// <value>The Name property gets/sets the value of the string field, _name.</value> public string Name { get { return _name; } set { _name = value; } } } /// text for class MainClass public class MainClass { /// text for Main static void Main() { } }
第一个帮助文件建立工程
（1）选择File|New Project
（2）为新工程选择保存目录，之后会显示Project Explorer Window和Project Properties Window
（3）现在不管properties window,右键Project Explorer中的Documentation Sources节点，选择Add Documentation Source，一个Document source是一个assembly文件或Visual Studio 解决方案或工程文件。
（4）现在添加reference assembly。
（5）现在可以构建帮助文档了，选择Documentation|Build Project，之后会显示Output Window并显示构建信息。
（6）完成之后，可以使用Documentation|View Help File菜单项浏览帮助文件，View Help File会根据构造类型进行显示 。
如果在构建中遇到什么问题，查找：http://www.ewoodruff.us/shfbdocs/html/355bb237-acf6-4df8-bfc6-d89736837abb.htm
为命名空间生成帮助
Sandcastle also supports the ndoc-style namespace documentation, which allows you to stick the documentation in the source files:
Simply create a non-public class called NamespaceDoc in the namespace you want to document, and the xml doc comment for that class will be used for the namespace.
Adorn it with a [CompilerGenerated] attribute to prevent the class itself from showing up in the documentation.
Example:
namespace Some.Test{/// <summary>/// The <see cref="Some.Test"/> namespace contains classes for ..../// </summary>[pilerGenerated]class NamespaceDoc{}}
最后欢迎大家访问我的个人网站:1024s
