C#的多个异常的XML文档注释

Question

我正在寻找一个指南，如何在 C# DLL 中的公共方法中记录多个异常。

例如：

/// <summary>
/// This method does something
/// </summary>
/// <param name="p_Parameter1">First parameter</param>
/// <param name="p_Parameter2">Second parameter</param>
/// <param name="p_Number">A number</param>
/// <exception cref="ArgumentNullException">
/// Thrown if p_Parameter1 is null</exception>
/// <exception cref="ArgumentNullException">
/// Thrown if p_Parameter2 is null</exception>
/// <exception cref="ArgumentNullException">
/// Thrown if any element of p_Parameter2 is null</exception>
/// <exception cref="ArgumentOutOfRangeException">
/// Thrown if p_Number is below or equal 0</exception>
/// <returns>A object</returns>

public static object DoSomething(
    object p_Parameter1, IList<object> p_Parameter2, 
    object p_Parameter3, int p_Number)
{
    if(p_Parameter1 == null)
        throw new ArgumentNullException(
            paramName:"p_Parameter1", 
            message:"Parameter is needed");
    if (p_Parameter2 == null)
        throw new ArgumentNullException(
            paramName: "p_Parameter2", 
            message: "Parameter is needed");

    for (int i = 0; i < p_Parameter2.Count; i++)
    {
        if(p_Parameter2[i] == null)
            throw new ArgumentNullException(
                paramName: String.Format("p_Parameter2[{0}]", i),
                message: "All elements have to be initialized");
    }

    if(p_Number < 0)
        throw new ArgumentOutOfRangeException(
            paramName: "p_Number", 
            message: "Parameter should be bigger then zero");

    var returnValue = new object();

    // do something where p_Parameter3 == null is allowed

    return returnValue;
}

这是正确的异常文档化方式吗？我应该为每种情况添加一个异常标签，还是仅为所有不允许为空值的参数添加一个标签？

/// <exception cref="ArgumentNullException">
/// Thrown if p_Parameter1, p_Parameter2
/// or any element of p_Parameter2 are null</exception>

- germanSharper

Answer 1

我会将异常按类型分组，例如：如果p_Parameter1、p_Parameter2或p_Parameter2的任何元素为空，则抛出异常。

作为参考，请查看MSDN文档中的示例：

ArgumentNullException   |   Either path, contents, or encoding is null.

- H H

---

你说得对，你的例子也表明使用“-或-”（UnauthorizedAccessException）是很常见的。在我看来，分组可能会导致忽略异常的某些原因。但如果每个人都这样做，那就随大流吧 ;) - germanSharper

“- 或 -” 分组似乎是 Microsoft 文档呈现多个 exception 标签的方式。请参见例如 TrySetException(IEnumerable<Exception>) 和相应的 源代码。 - Simon Touchtech

Answer 2

在这种情况下，MSDN是一个很好的模拟来源，浏览一些函数和链接，看起来他们倾向于使用一个exception块并在其中枚举不同的参数。

这样做可以让您的代码使用者更容易知道可能要捕获哪些异常，因为查看不同异常列表比查看包含重复异常的列表更容易理解。

- Patrick Quirk