在代码中使用 XML 文档

• 下载源代码 - 19.09 KB

引言

许多初学者和中级 C# 开发人员实际上是通过阅读有关方法的文档来了解要使用哪个确切的方法。例如，当我刚开始进行网络编程时，我通过“附加到类并显示在 Intellisense 中的描述”完全理解了 IPEndPoint 是什么。

好了，技术术语是“文档”，由于我们很快就会看到它是用 XML 完成的，所以它被称为 XML 文档。我所说的内容在下面的图表中有所说明。

入门

话不多说，让我们开始吧。创建一个简单的控制台应用程序，随意命名—例如，XML_Doc 是一个不错的名字。我们将保持方法简单，并处理一些基础数学。所以，添加一个类并称之为 PhysicsLib。您也可以直接添加我提供的代码，这样就不用重写了。或者，如果您知道自己在做什么，也可以使用自己实现的类。

PhysicsLib 包含一个函数 getDistance() 的定义，该函数有 1 个重载。这仅仅是为了计算当用户输入初始速度、加速度和最终速度或运动时间时的行驶距离。它还包含两个常量（真空中的光速和特征阻抗）以及另一个名为 Conversions 的类，用于帮助我们将加仑转换为升，将马力转换为千瓦。

本文的重点是展示如何通过 IntelliSense 功能向代码用户说明每个方法实际做什么以及每个类包含什么，就像所有内置的 .NET 函数一样。

有两种方法可以做到这一点。一种是直接在类文件中编写 XML，我们稍后会简要介绍，以便您确切了解它是如何工作的。第二种方法更简单，非常非常简单。我们将使用类图，从表中记录代码，然后让 Visual Studio 编写 XML。（不要总是让 IDE 为您编写代码，除非您别无选择，因为它帮助不大！）

我们必须严格区分我们在 C# 中使用类的两种方式，因为这对 XML 文档也很重要。第一种，我们可以选择只向项目中添加一个类（*.cs）文件。第二种，我们可以选择导入一个预编译的类库（DLL）并将其添加为项目的引用，然后使用 using 指令调用它。如果我们选择后者，在许多实际情况下都会这样做，我们将需要生成与 DLL 相关联的 XML 文档文件，它本身就是一个 XML 文件。如果我们只是像我们所做的那样将一个类添加到代码中，那么我们就不需要生成这个 XML 文件。我们将研究这两种方法。

在 PhysicsLib.cs 中，就在类声明之前，插入三个斜杠 ///。它会自动添加一些类似 XML 的代码，如下所示。

/// <summary>
/// Contains fundamental calculations, constants and conversions
/// </summary>

<summary> 标签用于保存有关类和方法的文本。例如，在这种情况下，它们说明了 PhysicsLib 包含的内容。有了这个，您就可以神奇地看到一些文档了，如果您尝试声明一个新的 PhysicsLib 对象。只需尝试在主程序中键入 phy… 您将看到如下所示的内容。

其他要点

好的。现在我们开始步入正题了。让我们继续。如前所述，内部有一个方法 getDistance()。它有 3 个参数，我们想记录其中的每一个。我们将只处理第一个定义；第二个重载将留给您来处理。

现在对于参数，我们通过在 <param> 标签中指定参数名称来记录它们。描述是出现在参数标签之间的值。它是标准的 XML，并且非常简单，如下所示。只需在要记录的 getDistance() 方法之前键入三个斜杠。以下内容将出现：

/// <summary> 
/// INSERT DESCRIPTION HERE 
/// </summary> 
/// <param name="U"> INSERT DESCRIPTION HERE </param> 
/// <param name="Acc"> INSERT DESCRIPTION HERE </param> 
/// <param name="V"> INSERT DESCRIPTION HERE </param>

例如，对于参数名称为“U”的地方，我们说明这是初始速度。IDE 自动为我们获取了所有可用的变量，并为我们生成了 XML。您的工作只是填写您的描述。我们现在可以测试我们的工作了。下图显示了我的示例。[请注意，要使 getDistance() 的文档显示在所有重载上，您必须在所有重载的 summary 标签中都包含它。]

使用类图查看器插入 XML 文档

这是做所有事情的更简单的方法。我们在解决方案资源管理器中启动类图查看器，然后填写相应的摘要表。它使用树形层次结构，这使我们能够查看所有类、方法和变量。我的类图如下所示。

当您单击任何可用的类型（方法、常量或类）时，您会发现它会在下方打开一个表格，其中有一个摘要列。这就是您填写文档的列。它非常易于查看和操作，因此我不会写太多关于它的内容。Visual Studio 将自动为您添加所有必要的 XML，然后，您就完成了！

使用 DLL 时

当使用一个预编译的类库并在另一个应用程序中用作引用时，过程会略有不同。这个类必须随其文档一起移动。这样做很简单，我们将 Visual studio 设置为输出 XML 格式的文档。强烈建议将此文件存储在与 DLL 相同的文件夹中，因为 IDE 会从那里查找它。您是否熟悉“文档仍在构建中。请稍后重试？”这句话？当 IDE 仍在遍历您尝试访问的类/方法/变量关联的 XML 文档文件时，就会发生这种情况。

要将 IDE 设置为输出此 XML 文件，您需要编辑生成选项。并将其设置为在所需位置输出此文件。**右键单击** **解决方案资源管理器**中的项目文件。会打开一个如下所示的窗口。

勾选 XML 文档复选框并保存对项目的更改。构建时，XML 文档文件将在那时生成。您现在可以携带您的库和您的文档了。享受吧！

历史

• 2009年1月29日：初始发布