Sandcastle生成帮助文档
生成帮助文件软件选择
Sandcastle的使用
介绍
安装
使用
为了创建帮助文件，需要开启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个斜杠（///）开头。可以参考：http://msdn.microsoft.com/zh-cn/library/b2s063f7.aspx
| 标记 | 说明 |
| <c> | 把行中的文本标记为代码，例如<c> int i =10</c> |
| <code> | 把多行标记为代码 |
| <example> | 标记为一个代码示例 |
| <exception> | 说明一个异常类（编译器要验证其语法） |
| <include> | 包含其他文档说明文件的注释（）（编译器要验证其语法） |
| <list> | 把列表插入到文档中 |
| <para> | 建立文档的结构 |
| <param> | 标记方法的参数（编译器要验证其语法） |
| <paramref> | 表示一个单词是方法的参数（编译器要验证其语法） |
| <permission> | 说明对成员的访问（编译器要验证其语法） |
| <remarks> | 给成员添加描述 |
| <returns> | 说明方法的返回值 |
| <see> | 提供对另一个参数的交叉引用（编译器要验证其语法） |
| <seealso> | 提供描述中的参见部分（编译器要验证其语法） |
| <summary> | 提供类型或成员的简短描述 |
| <typeparam> | 用在泛型类型的注释中以说明一个类型参数 |
| <typepararef> | 类型参数的名称 |
| <value> | 描述属性 |
<c>text</c>
// compile with: /doc:DocFileName.xml
/// text for class TestClass
public class TestClass
{
/// <summary><c>DoWork</c> is a method in the <c>TestClass</c> class.
/// </summary>
public static void DoWork(int Int1)
{
}
/// text for Main
static 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>
对可从当前编译环境中获取的异常的引用。 编译器检查到给定异常存在后，将 member 转换为输出 XML 中的规范化元素名称。 member 必须位于双引号 (" ") 中。
/// Comment for class
public class EClass : System.Exception
{
// class definition...
}
/// Comment for class
class TestClass
{
/// <exception cref="System.Exception">Thrown when...</exception>
public void DoSomething()
{
try
{
}
catch (EClass)
{
}
}
}<include file='filename' path='tagpath[@name="id"]' />
包含文档的 XML 文件的名称。 该文件名可用路径加以限定。 将 filename 括在单引号 (' ') 中。
filename 中指向标记 name 的标记路径。 将此路径括在单引号中 (' ')。
注释前边的标记中的名称说明符；name 具有一个 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>
要定义的项，该项将在 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> 标记使您得以将成员的访问记入文档。 使用 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()
{
}
}
/// 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>
[System.Runtime.CompilerServices.CompilerGenerated]
class NamespaceDoc
{
}
}