Sandcastle生成帮助文档

2023-10-26 02:51:51

生成帮助文件软件选择

如要想与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

标记	说明
	把行中的文本标记为代码，例如 int i =10
	把多行标记为代码
	标记为一个代码示例
	说明一个异常类（编译器要验证其语法）
	包含其他文档说明文件的注释（）（编译器要验证其语法）
	把列表插入到文档中
	建立文档的结构
	标记方法的参数（编译器要验证其语法）
	表示一个单词是方法的参数（编译器要验证其语法）
	说明对成员的访问（编译器要验证其语法）
	给成员添加描述
	说明方法的返回值
	提供对另一个参数的交叉引用（编译器要验证其语法）
	提供描述中的参见部分（编译器要验证其语法）
	提供类型或成员的简短描述
	用在泛型类型的注释中以说明一个类型参数
	类型参数的名称
	描述属性

示例说明：

text

// compile with: /doc:DocFileName.xml /// text for class TestClass
public class TestClass
{/// DoWork is a method in the TestClass class./// 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
{/// /// TestClass contains several cref examples./// 
public class TestClass{/// /// This sample shows how to specify the  constructor as a cref attribute./// 
public TestClass(){ }/// /// This sample shows how to specify the  constructor as a cref attribute./// 
public TestClass(int value){ }/// /// The GetZero method./// 
///  /// This sample shows how to call the  method./// /// class TestClass /// {///     static int Main() ///     {///         return GetZero();///     }/// }/// /// public static int GetZero(){return 0;}/// /// The GetGenericValue method./// 
///  /// This sample shows how to specify the  method as a cref attribute./// public static T GetGenericValue(T para){return para;}}/// /// GenericClass./// 
///  /// This example shows how to specify the  type as a cref attribute./// class GenericClass{// Fields and members.}class Program{static int Main(){return TestClass.GetZero();}}
}

destription

cref = "member"

对可从当前编译环境中获取的异常的引用。编译器检查到给定异常存在后，将 member 转换为输出 XML 中的规范化元素名称。 member 必须位于双引号 (" ") 中。

/// Comment for class
public class EClass : System.Exception
{// class definition...
}/// Comment for class
class TestClass
{/// Thrown when...public void DoSomething(){try{}catch (EClass){}}
}

filename

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

tagpath

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

name

注释前边的标记中的名称说明符；name 具有一个 id。

位于注释之前的标记的 ID。将此 ID 括在双引号中 (" ")。

/// 
class Test
{static void Main(){}
}/// 
class Test2
{public void Test(){}
}

xml_include_tag.doc



The summary for this type.



The summary for this other type.


 
  
  
  
termdescriptiontermdescription
 
term 
要定义的项，该项将在 description 中定义。 
description 
项目符号列表或编号列表中的项或者 term 的定义。 
  
/// text for class TestClass public class TestClass { /// Here is an example of a bulleted list: ///  ///  /// Item 1. ///  ///  /// Item 2. ///  ///  /// 
 static void Main() { } } 
  
content 
 标记用于诸如 
、 或  等标记内 
  
description 
 标记应当用于方法声明的注释中，以描述方法的一个参数。 如要记录多个参数，请使用多个  标记。 
  
 
 标记提供了指示代码注释中的某个单词（例如在 
 或  块中）引用某个参数的方式。 可以处理 XML 文件来以不同的方式格式化此单词，比如将其设置为粗体或斜体。 
  
  
/// text for class TestClass public class TestClass { /// DoWork is a method in the TestClass class. /// The  parameter takes a number. /// 
 public static void DoWork(int Int1) { } /// text for Main static void Main() { } } 
  
  
  
description 
 标记使您得以将成员的访问记入文档。 使用 PermissionSet 类可以指定对成员的访问。 
  
  
class TestClass { /// Everyone can access this method. public static void Test() { } static void Main() { } } 
  
  
///  /// You may have some primary information about this class. /// 
 ///  /// You may have some additional information about this class. ///  public class TestClass { /// text for Main static void Main() { } } 
  
  
/// text for class TestClass public class TestClass { /// Returns zero. public static int GetZero() { return 0; } /// text for Main static void Main() { } } 
  
  
 
 标记使您得以从文本内指定链接。 使用  指示文本应该放在“另请参见”节中。 用 cref 特性创建指向代码元素的文档页内部超链接。 
  
  
/// text for class TestClass public class TestClass { /// DoWork is a method in the TestClass class. /// Here's how you could make a second paragraph in a description.  for information about output statements. ///  /// 
 public static void DoWork(int Int1) { } /// text for Main static void Main() { } } 
  
description 
  
  
  
/// comment for class public class TestClass { ///  /// Creates a new array of arbitrary type  /// 
 /// The element type of the array public static T[] mkArray(int n) { return new T[n]; } } 
  
  
  
  
/// text for class Employee public class Employee { private string _name; /// The Name property represents the employee's name.
 /// The Name property gets/sets the value of the string field, _name. 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
{/// /// The  namespace contains classes for ..../// [System.Runtime.CompilerServices.CompilerGenerated]class NamespaceDoc{}
}
 
  
最后欢迎大家访问我的个人网站: 1024s
                        
                        
本文来自互联网用户投稿，文章观点仅代表作者本人，不代表本站立场，不承担相关法律责任。如若转载，请注明出处。 如若内容造成侵权/违法违规/事实不符，请点击【内容举报】进行投诉反馈！