C#文档自动生成方法
1. 安装Sandcastle .(网上可下载)
2. 安装Sandcastle Help File Builder.(网上可下载)
3. 安装完成后, 打开Sandcastle Help File Builder工具直接新建项目。新建后,主窗口会直接打开项目属性,这里就是对生成文档的主要配置区域。我们先添加需要生成文档的源。右击项目中的Documentation Sources可以添加多种文件类型(sln,proj,xml,dll,exe) 。如果选择sln类型文件,而在生成过程出现SHFB: Warning BE0062: No XML comments files found. The help file will not contain any member comments错误,说明了XML文件没有生成。此时,可以你可以利用VS自己去生成XML(工程->属性->build->xml文档文件选中,默认情况下跟生成的EXE文件放在同一目录的)。成功生成后,然后选择XML类型文件做为数据源即可生成C#文档。
4. 对主要的属性进行设置.
FrameworkVersion: 选择对应的Framework版本
HelpFileFormat : 选择需要生成的文档的格式. 注意这里选定的格式要在下面对应的地方进行设置. 注意对于不同的格式还需要安装不同的编译工具 Helpe1x(chm)需要安装Microsoft HTML Help,Helper2x(Hxs)需要安装Hxcomp.
NamespaceSummaries: 选择需要生成的命名空间,直接点击开窗选择。
Lanugages :语言一定要选择中文,这会使一些文档里的一些文字自动生成中文
CopyrightHref:版权链接
CopyrightText: 版权文字
HelpTitle: 文档标题
HtmlHelpName:文档生成文件名称
PresentationStyle: 这里现在支持vs 2005,Prototype等格式 ,根据自己需要选择
OutputPath:生成路径
Show Missing Tags:下面的一些设置根据需要在最终版生成时设置成True,不然会在文档中出现红色的提示.
Visibility: 设置了哪些信息可以在HELP文档中显示。比如:属性DocumentPrivateFields = false的情况下,如果类成员变量为private型,则此变量的信息不会生成HELP文档。反之,属性DocumentPrivateFields = true的情况下,即使类成员变量为private型,此变量的信息也会生成HELP文档。
5.点击上面的生成菜单或者按钮,就可以直接打开生成过程界面,在这里可以直接查看生成过程中的一些提示和错误. 生成完成后,一个MSDN风格一致的文档就出来了:
注释风格如下:
using System;
using System.Collections.Generic;
using System.Diagnostics.CodeAnalysis;
using System.Runtime.Serialization;
namespace TestNamespace
{
/// <summary>
/// Tests whether sandcastle can handle all c# tags as defined at http://msdn2.microsoft.com/en-us/library/5ast78ax.aspx.
/// Comments of method "Increment (int step)" include almost all tags.
/// Method "Swap" is used to test generics tags, such as "typeparam".
/// <threadsafety static="true" instance="false"/>
/// </summary>
[Serializable()]
public class StoredNumber
{
/// <summary>Initializes the stored number class with a starting value.</summary>
public StoredNumber(int value)
{
number = value;
}
private int number;
/// <preliminary>
/// <para>This method is just for testing right now. It might be removed in the near future</para>
/// </preliminary>
public void PreliminaryTest()
{
}
/// <overloads>
/// <summary>test overlads tag</summary>
/// </overloads>
public void Dec()
{
number--;
}
/// <summary>
/// dec by a specified step
/// </summary>
/// <param name="step"></param>
public void Dec(int step)
{
number -= step;
}
/// <summary><c>Increment</c> method incriments the stored number by one.
/// <note type="caution">
/// note description here
///</note>
/// <preliminary/>
/// </summary>
public void Increment()
{
number++;
}
/// <summary><c>Increment</c> method incriments the stored number by a specified <paramref name="step"/>.
/// <list type="number">
/// <item>
/// <description>Item 1.</description>
/// </item>
/// <item>
/// <description>Item 2.</description>
/// </item>
/// </list>
/// <para>see <see cref="System.Int32"/></para>
/// <para>seealso <seealso cref="System.Int64"/></para>
/// </summary>
/// <remarks>
/// You may have some additional information about this class.
/// </remarks>
/// <example> This sample shows how to call the GetZero method.
/// <code>
/// class TestClass
/// {
/// static int Main()
/// {
/// return GetZero();
/// }
/// }
/// </code>
/// </example>
///
/// <exception cref="System.Exception">Thrown when...</exception>
/// <param name="step"> specified step</param>
/// <permission cref="System.Security.PermissionSet">Everyone can access this method.</permission>
/// <returns>Returns nothing</returns>
/// <value>The Name property gets/sets the _name data member.</value>
public void Increment(int step)
{
number = number + step;
}
/// <summary>
/// Swap data of type <typeparamref name="T"/>
/// </summary>
/// <param name="lhs">left <typeparamref name="T"/> to swap</param>
/// <param name="rhs">right <typeparamref name="T"/> to swap</param>
/// <typeparam name="T">The element type to swap</typeparam>
public void Swap<T>(ref T lhs, ref T rhs)
{
T temp;
temp = lhs;
lhs = rhs;
rhs = temp;
}
/// <summary>Gets the stored number.</summary>
public int Value
{
get
{
return (number);
}
}
private int _myProp;
///<summary>
///see <see langword="null"/> as reference
///</summary>
public int MyProp
{
get { return _myProp; }
set { _myProp = value; }
}
}
}