如何实现构造方法参数复用已有字段的XML注释？

嘿，我之前也碰到过这个头疼的问题——想用字段的XML注释给构造函数参数复用，试了<see>、<seealso>甚至普通的<inheritdoc>都不管用。其实是咱们没用到正确的XML注释语法，下面给你两种靠谱的解决方案：

方法一：用带path的<inheritdoc>直接复用（无需额外文件） #

这个方法最直接，不用拆分注释到外部文件，只要在参数的注释里指定要继承字段的summary内容就行。代码示例：

/// <summary>
/// A foo string in the file.
/// </summary>
public string Foo;

/// <param name="foo"><inheritdoc cref="Foo" path="summary/node()"/></param>
public Main(string foo) { this.Foo = foo; }

为什么这样能行？ #

• 普通的<inheritdoc cref="Foo"/>在参数注释里不会自动继承字段的summary，因为参数注释和字段注释的XML结构不同。
• path="summary/node()"明确告诉编译器：提取Foo字段注释里summary标签下的所有内容，直接放到参数的注释里。

现在鼠标悬停在构造函数的foo参数上，就能看到和Foo字段完全一样的注释内容了！

方法二：用<include>拆分共享注释（适合多处复用） #

如果你的注释需要在多个类或字段/参数之间复用，把共享内容放到单独的XML文件里会更方便：

1. 新建一个SharedComments.xml文件，内容如下：

<doc>
  <members>
    <member name="FooSummary">
      <summary>A foo string in the file.</summary>
    </member>
  </members>
</doc>

2. 在你的C#代码里，字段和参数都引用这个共享注释：

/// <include file="SharedComments.xml" path="doc/members/member[@name='FooSummary']/summary/*"/>
public string Foo;

/// <param name="foo"><include file="SharedComments.xml" path="doc/members/member[@name='FooSummary']/summary/*"/></param>
public Main(string foo) { this.Foo = foo; }

注意事项 #

• 确保SharedComments.xml的"复制到输出目录"设置为"始终复制"或"如果较新则复制"，否则编译器找不到它。
• 这个方法适合注释内容需要在多个地方保持一致的场景，修改一次XML文件就能同步所有引用的地方。

为什么之前的标签没用？ #

• <see>和<seealso>：这两个标签只是生成指向字段的链接，不会把字段的注释内容复制到参数的悬停提示里。
• 普通<inheritdoc cref="Foo"/>：参数注释的上下文和字段不同，编译器不知道该继承字段的哪部分内容，所以需要用path明确指定。

内容的提问来源于stack exchange，提问作者Cleax