Sandcastle生成帮助文档

最新推荐文章于 2023-06-08 13:53:42 发布

崔世勋

最新推荐文章于 2023-06-08 13:53:42 发布

阅读量1.5k

点赞数

分类专栏： c#

本文链接：https://blog.csdn.net/CHS007chs/article/details/30040651

版权

c# 专栏收录该内容

33 篇文章 1 订阅

订阅专栏

生成帮助文件软件选择

如要想与VS集成在一起，可以使用

（1）Sandcastle Help File Builder http://shfb.codeplex.com/

（2）DocProject http://docproject.codeplex.com/

（3）GhostDoc http://submain.com/products/ghostdoc.aspx

如果不用与VS集成在一起，可以使用

（1）Doxygen http://www.stack.nl/~dimitri/doxygen/

（2）Docu http://docu.jagregory.com/

（3）NDoc3 http://sourceforge.net/projects/ndoc3/

Sandcastle的使用

介绍

Sancastle由微软创建于2006，软件包含两部分：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 ,下载地址： http://msdn.microsoft.com/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个斜杠（///）开头。可以参考：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>	描述属性

示例说明：

// 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>

cref = "member"

对可从当前编译环境中获取的异常的引用。编译器检查到给定异常存在后，将 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)
        {
        }
    }
}

filename

包含文档的 XML 文件的名称。该文件名可用路径加以限定。将 filename 括在单引号 (' ') 中。

tagpath

filename 中指向标记 name 的标记路径。将此路径括在单引号中 (' ')。

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>

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> 标记提供了指示代码注释中的某个单词（例如在 <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> 标记使您得以从文本内指定链接。使用 <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>

    [System.Runtime.CompilerServices.CompilerGenerated]
    class NamespaceDoc
    {
    }
}

最后欢迎大家访问我的个人网站: 1024s

崔世勋

关注

0
点赞
踩
0

收藏

觉得还不错? 一键收藏
0
评论
Sandcastle生成帮助文档

生成帮助文件软件选择如要想与VS集成在一起，可以使用（1）Sandcastle Help File Builder http://shfb.codeplex.com/（2）DocProject http://docproject.codeplex.com/（3）GhostDoc http://submain.com/products/ghostdoc.aspx如果不用...
复制链接

扫一扫