C# 在Xml注释中提供哪些信息？

当我编写一个方法并想要对其进行注释时，我会将相同的信息写入summary标记中

例如：

/// <summary>
/// Get a <typeparamref name="Customer">customer</typeparamref> by its ID 
/// </summary>
/// <param name="id">customer id</param>
/// <returns>a <typeparamref name="Customer">customer</typeparamref></returns>
private Customer GetCustomerById(string id)
{
   ...
}

//
///通过ID获取客户
/// 
///客户id
///顾客
私有客户GetCustomerById（字符串id）
{
...
}

---

最后，这真的有用吗？提供什么信息以及在哪个标签中提供这些信息？

另一个问题的答案也将回答您的问题：

提供文档真的有用吗

---

提供任何你想要的，你认为需要的和有用的。在Visual Studio中，这些信息将作为IntelliSense工具提示显示给代码使用者，就像您在.NET类和成员中看到的一样。

如果您正在开发库，Xml文档非常有用。可以根据这些xml注释自动生成帮助文件。有关生成帮助文件的详细讨论，请参阅。有关Xml文档标记的信息，请查看。

有时方法或属性名称是自解释的，但情况并非总是如此。用你的例子来描述这个事件。您应该提供如果提供的ID不存在会发生什么情况的信息。你的方法会抛出一个异常（如果是的话，那么它会是什么异常）还是仅仅返回null，或者某种普通的Customer.Empty值？有时您甚至可以提供一些代码示例

无论哪种方式，在任何情况下提供代码文档都是一种很好的做法。

考虑干燥（不要重复）。param条目描述参数，returns条目描述返回的内容。摘要应概述该方法的作用，而不是重复其他条目中的信息

您的文档缺少的是实际文档。“字符串id”是一个包含id的字符串，它是自文档化的。但是我如何调用这个方法：什么组成了一个有效的用户id？如果传入null或空字符串，会发生什么？等等

下面是一个假设的示例，其中包括有关事物的用途以及如何使用该方法的文档：

/// <summary> Gets information on a customer </summary>
///
/// <param name='id'> A customer identifier in the form of a GUID string.
/// e.g. "{D8C447DD-0E7F-4C8B-A3E5-2C6E160D297B}".
/// Braces around the GUID are optional.
/// This parameter must be a valid Guid. </param>
///
/// <returns> A Customer record describing the given customer, or
/// null if the Customer is not found</returns>

///获取有关客户的信息
///
///GUID字符串形式的客户标识符。
///例如“{D8C447DD-0E7F-4C8B-A3E5-2C6E160D297B}”。
///GUID周围的大括号是可选的。
///此参数必须是有效的Guid。
///
///描述给定客户的客户记录，或
///如果未找到客户，则为null

---

如果您使用像my addin（）这样的工具，那么围绕类复制这些参数详细信息是很简单的，因此很好地记录您的方法不需要花费时间。

在很多情况下，我发现最好完全删除返回元素。看来你的例子就是一个很好的例子。谢天谢地，VStudio没有用警告来标记这是一个不好的评论。我这样做的原因是，在80%以上的情况下，我的文档基本上描述了返回类型的全部内容，或者，函数的名称非常明显，在我的估计中，包含它是对时间和精力的无用浪费，而且它经常导致违反DRY

你的例子就是一个很好的例子

Customer GetCustomerById(string id)

---

如果这是一个int-id，那么这个函数甚至可能不需要注释。如果是字符串，则不太清楚，可能需要一些澄清。但无论哪种情况，在返回类型上提供XML注释似乎都是一种浪费。请记住，这是一个主观问题，有些人可能希望为了完成而始终包含返回类型的注释，这很好。不过，我很高兴这不是必需的，从VStudio的警告系统开始。

我认为人们在决定xml注释是否有用时常常忽略了这一点。对我来说，我评论我创建的每个公共方法和类只是为了保持一致。通过适当的工具，添加这些注释既不困难也不耗时，而且它为您提供了一个清晰的位置来描述您的使用期望。（仅供参考：适合我的工具是ReSharper）