C#文档自动生成方法

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; }
        }

    }

}