我能否在构造函数注释中引用属性注释？

Question

如果我的类有一个被注释的公共属性，并通过构造函数进行赋值，那么我能否从具有相同名称的构造函数参数的描述中引用它的描述？

public class MyClass
{
    /// <summary>
    /// x description
    /// </summary>
    public int x { get; private set; }
    /// <summary>
    /// y description
    /// </summary>
    public int y { get; private set; }
    /// <summary>
    /// Constructor description
    /// </summary>
    /// <param name="x">How do I reference x description from here?</param>
    /// <param name="y">And y description?</param>
    public MyClass(int x, int y)
    {
        this.x = x;
        this.y = y;
    }
}

- user2136963

Answer 1

你不能在描述中包含，但可以使用<see>标签链接到属性文档。例如：

<param name="x">The initial value for <see cref="x"/></param>

顺便提一下，我强烈建议您遵循.NET命名规范，其中公共成员以大写字母开头。

- Jon Skeet

---

但我仍然想知道如何使用 cref，我打开了生成的 xml，只看到 x 被替换为 x 的全名，并没有在智能感知中看到“x 描述”。 - Lei Yang

@LeiYang：不，正如我所说的那样，这不会“包括”描述 - 但是当您生成文档时，HTML 中将有指向该属性的链接。 - Jon Skeet

我认为这个答案已经过时了（不确定是从什么时候开始）。我提供了一个单独的方法作为答案，它适用于C# 9以及之前的版本。 - Luke

Answer 2

可以使用<inheritdoc/>来实现，具体是通过使用可选的cref和path属性。

注意：我不确定这个功能是什么语言或框架版本推出的，但我在.NET 5 / C# 9中使用它是可行的。如果有人评论起始版本，我可以进行编辑。

参考：https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/recommended-tags#inheritdoc

对于你的示例（区别在构造函数XML注释的param元素内）：

public class MyClass
{
    /// <summary>
    /// x description
    /// </summary>
    public int x { get; private set; }
    /// <summary>
    /// y description
    /// </summary>
    public int y { get; private set; }
    /// <summary>
    /// Constructor description
    /// </summary>
    /// <param name="x"><inheritdoc cref="x" path='/summary'/></param>
    /// <param name="y"><inheritdoc cref="y" path='/summary'/></param>
    public MyClass(int x, int y)
    {
        this.x = x;
        this.y = y;
    }
}

这将使构造函数参数继承您的参数摘要注释，减少冗余。

- Luke

---

这对我来说行不通。生成的文档中显示的是整个<inheritdoc>标签，而不仅仅是摘要字段的解析内容。 - Cassie Dee

@CassieDee 如果没有看到代码，我很难确定你的问题是什么。建议你提出一个新的问题，并包含一个最小可复现的示例。如果你在评论中附上链接，我会很乐意去看一下，除非有其他人比我更快。在问题本身中引用这个答案，并说明你已经尝试了我在这里提供的方法，以避免被标记为重复问题。请同时提供你的.NET SDK版本。 - Luke

工作得很好，我很高兴学会了这个！ - Gaspa79