C# 中的文档

引言

在软件开发生命周期中，文档编写始终是一项被忽视的任务。在开发应用程序时，大多数软件开发专业人士，包括资深专业人士，往往会忽略文档编写，尽管每个人都知道在代码维护应用程序时会遇到的困难。文档编写是一个非常重要的方面，尤其是在开发涉及多个模块的大型应用程序时。

在使用 C# 开发应用程序时，我们可以尽量减少制作和维护应用程序文档的工作量。作为一名 C# 应用程序开发者，编写内联注释是很常见的，这些内联注释可以成为生成强大且更准确文档的来源。内联注释是任何代码中最重要的部分，因为它们提供了关于所编写代码部分的有价值信息。最重要的是，它们是在系统构建时编写的。C# 编译器的一个出色功能是它支持使用代码中编写的注释自动创建文档，唯一的区别是文档以 XML 形式生成。与各种编程语言提供的其他自动文档生成器（它们生成基于 HTML 的文档）不同，C# 生成 XML，但有一些工具可以将 XML 文件作为输入并生成基于 HTML 的文档。由于 C# 将所有注释存储在 XML 文件中，用户可以灵活地从 C# 中开发优秀的文档。代码注释、用户手册、开发人员手册、测试计划以及许多其他文档都可以使用 XML 标签从单个源生成。

生成基于 XML 的文档的过程是通过向代码的各个部分添加注释来完成的。这个过程可以按以下方式描述：

Source file  (.cs) -> C# Compiler (csc.exe) -> XML Documentation (doc.xml) 
                -> HTML/ Visual Studio Based Documentation

C# 文档深入解析

在我们深入探讨自动化文档部分之前，先来看看在开发基于 XML 的文档时需要了解的一些重要方面。主要的一点是，注释需要以“///”开头，因为这是编译器识别用于基于 XML 的文档的标签的方式。“//”注释方式在 C# 中也支持，但通常情况下，编译器会忽略在此之后的内容，但当编译器遇到另一个“/”时，这表明这是一个 XML 注释，需要妥善处理。通常，三个斜杠后面是 XML 标签，其中包含所需的属性和值。
例如

/// <Summary>
/// this is a place where something is done
/// </Summary>

有各种预定义的标签可用于生成文档。开发人员可以自由使用任何类型的 XML 标签来记录代码，唯一的要求是这些标签需要符合 XML 语法。预定义标签指示正在提供哪种类型的文档信息，编译器会针对这些信息的一些方面验证这些标签并生成输出。其他元素用于布局和/或格式化。C# 编译器会处理嵌入在 XML 标签内的这些注释，并构建基于 XML 的文档。当遇到无效引用时，它会生成错误。

以下列表描述了提供的主要文档元素。要记住的重要一点是，每个元素都应该写在其开始和结束标签之间。此外，某些标签需要一些额外的强制属性。例如，'cref' 属性可以在任何元素中使用，但只有在可行时才应使用。

一些格式化标签如下：

<list type=""table"">
<listheader>
<term>Employee</term>
<description>Employee Type</description>
</listheader>
<item>
<term>XXXX</term>
<description>Administrator</description>
</item>
<item>
<term>YYYY</term>
<description>User</description>
</item>
</list>"

C# 文档示例

让我们看一个例子，然后尝试使用上述信息来获取一个自动生成的文档文件。

上面是一个典型的应用程序在构建阶段的例子，然后我们在维护时会为函数或类的功能感到困惑！让我们添加一些注释并进行必要的处理。

using System; 
using System.Data; 

namespace ExampleDocumentation
{ 
/// <summary>
///  DocumentationClass: Is the class that will be used for explaining the 
///  example of automated documentation
/// </summary> 

    public class DocumentationClass
    { 
    /// <summary>
    /// public DocumentationClass () : 
    ///     Is the constructor used for DocumentationClass class
    /// </summary> 

    public DocumentationClass () 
    { 
    } 

    /// <summary>
    /// public void DocumentationClassMethod: Is a void method 
    /// that does not return anything and takes no parameters.
    /// It does the functionality of some addition and subtraction to 
    /// get the result
    /// </summary> 
    public void DocumentationClassMethod () 
    { 
    } 
   } 
}

正如你在上面所见，我们现在添加了一些有价值的注释，它们具有很高的价值。现在要生成文档，我们可以使用以下命令：

<Directory>\Microsoft.NET\Framework\v1.1.4322>csc csc 
                        DocumentationClass.cs /doc:doc.xml

在上面的命令中，/doc 指示编译器生成名为 _doc.xml_ 的文档。这将产生以下输出：

<?xml version="1.0"?>
<doc>
    <assembly>
        <name> DocumentationClass</name>
    </assembly>
    <members>
        <member name="T:ExampleDocumentation.DocumentationClass">
            <summary>
             DocumentationClass: Is the class that will be used 
             for explaining the example of automated documentation
            </summary> 
        </member>
        <member name="M:ExampleDocumentation.DocumentationClass.#ctor">
            <summary>
            public DocumentationClass () : 
            Is the constructor used for DocumentationClass class
            </summary> 
        </member>
        <member name=
    "M:ExampleDocumentation.DocumentationClass.DocumentationClassMethod">
            <summary>
            public void DocumentationClassMethod: 
            Is a void method that does not return anything 
    /// and takes no parameters. 
    ///It does the functionality of some addition and substation to 
            get the result
            </summary> 
        </member>
    </members>
</doc>

一些要点

一些常量通常会附加到被注释的对象上，这些是用于标识类型代码和部分的 ID。通常，它们被归类如下：

• N 表示命名空间 (Namespace)
• T 表示类型 (Type)，包括类 (class)、接口 (Interface)、结构体 (struct)、枚举 (enum) 或委托 (delegates)
• F 表示类的字段 (fields)
• P 表示属性索引器或索引属性 (Property indexer or indexed property)
• M 表示方法 (Methods)，特殊方法构造函数和运算符（重载）(special methods constructor and operator(overloaded))
• E 表示事件 (Events)
• ! 表示 C# 无法解析某些引用的错误字符串 (an error string that C# was unable to resolve some references)

使用 Visual Studio NET 2000 IDE 生成 C# 文档

可以从 Visual Studio NET 2000 IDE 以以下方式生成文档：

• 打开项目的属性页，通常通过在解决方案资源管理器中右键单击项目，然后单击“属性”。
• 单击“配置属性”文件夹。
• 单击“生成”选项。
• 在右侧窗格中，会有一个名为“XML 文档文件”的属性字段。在此输入所需信息，如文件名和路径。

使用 Visual Studio .NET 生成基于 HTML 的文档

C# 编译器生成的基于 XML 的文档可以用来生成基于 HTML 的文档。Visual Studio 会获取 C# 编译器生成的 _doc.xml_ 文件，并生成整个 HTML 页面的文档。要做到这一点，我们需要遵循相同的过程，然后转到 Visual Studio .NET 中的“工具”菜单，选择“生成注释的 Web 页”，会弹出一个对话框。在其中，选择要创建文档的项目。还可以选择解决方案的特定部分来生成文档。

C# 文档生成器的问题

C# 中的自动文档生成存在一些不足之处，以下是其中一些需要考虑的问题：

1. 如果任何情况下你忘记为任何方法添加注释，它将只会被忽略。
2. 即使编写了注释，但你使用了“//”而不是“///”，那么文档中也不会有这些注释的引用。
3. 生成 C# 文档时，只要有任何返回类型，就必须明确指定。