.NET 花式注释

momo3142022-11-18相同方式共享非商业用途署名转载

inheritdoc

inheritdoc 通常在实现类或者子类中使用，代表此方法或属性的注释与其父级的同名方法或属性完全相同


public interface IDefinitions
{
    /// <summary>
    /// 道具信息
    /// </summary>
    ItemDefinitions Items { get; }

    /// <summary>
    /// 技能信息
    /// </summary>
    SkillDefinitions Skills { get; }
}

public sealed class Definitions : IDefinitions
{
    /// <inheritdoc />
    public ItemDefinitions Items { get; private set; }

    /// <summary>
    /// <inheritdoc />
    /// </summary>
    public SkillDefinitions Skills { get; private set; }
}

注意：以上两种写法在效果上应该是完全一致的，不过为了简洁，我更倾向于选择第一种写法

inheritdoc 注释在 visual studio 中的效果

see / seealso

see / seealso 用法类型，都是用于在XML注释中插入一个能够指向其他类/属性/方法的超链接。该连接可以点击，点击后将跳转到对应的类/属性/方法。该链接默认使用其引用的类/属性/方法的名字作为链接文本，也支持使用InnerText的方式自定义文本。其引用被改名后，当前注释也会被自动修改（需要IDE支持）。


public enum SpecialEffect : byte
{
      /// <summary>
    /// 解除 <see cref="AbnormalState.Immobilize"/> 状态
    /// </summary>
    CureAbnormalState05 = 5,

    /// <summary>
    /// 解除 <see cref="AbnormalState.Silence">沉默 - [03]</see>、<see cref="AbnormalState.Darkness">失明 - [04]</see> 状态
    /// </summary>
    CureAbnormalState0304 = 20,
}

see / seealso 注释在 visual studio 中的效果

paramref

这种注释没有什么花里胡哨的效果，其主要作用就是为了在方法参数重命名时，IDE可以自动更新所有引用了此参数的注释文本。其参数引用无法通过InnerText的方式进行文本自定义，其文本虽然在 visual studio 中被显示为蓝色，但并不是超链接形式，也无法点击，甚至鼠标 hover 状态也无法显示任何信息。总之，只是为了解决方法参数重命名时，修改不全的问题。

/// <summary>
/// 检查指定武器类型 <paramref name="weapon"/> 是否能够使用此技能
/// </summary>
/// <param name="weapon">武器类型枚举值</param>
/// <returns></returns>
public bool CanUsedByWeapon(WeaponClass weapon)
{
    return Weapons[(int)weapon - 1];
}

paramref 注释在 visual studio 中的效果

list

此注释包含多种 XML 标签，分别是： <list>、<item>、<term>、<description>。

此种注释主要用于将注释显示为列表形式，一般在注释目标包含多种含义，或在不同情况下具有不同表现时才会使用。 visual studio 会将 <list> 标签包裹的部分以列表方式渲染：每个 <item> 标签为列表中的一个条目（条目中可以不使用任何标签，直接输入条目文本，也可以使用 <term> 和 <description> 标签分别表示 key - description 的内容）

public sealed class ItemModel
{
  /// <summary>
  /// 多种含义
  /// <list>
  /// <item>对于普通怪物，表示击杀怪物时所获得的金币数量的最大值</item>
  /// <item>对于行会排名赛怪物，表示击杀怪物时应该获得的行会点数</item>
  /// </list>
  /// </summary>
  public short MoneyMax { get; set; }

  /// <summary>
  /// 此字段有多种用途：
  /// <list>
  /// <item><term>武器</term><description>武器攻击速度</description></item>
  /// <item><term>坐骑</term><description>召唤时间（秒）</description></item>
  /// <item><term>强化石</term><description>可强化的最高等级</description></item>
  /// <item><term>技能道具</term><description>使用此道具时，触发的技能等级</description></item>
  /// </list>
  /// </summary>
  public byte AttackTime { get; set; }
}

list 注释在 visual studio 中的效果