Visual Studio - 摘要标记注释 - 可选参数答案

【问题标题】：Visual Studio - Summary Tag Comments - Optional ParamsVisual Studio - 摘要标记注释 - 可选参数
【发布时间】：2011-09-07 13:26:10
【问题描述】：

在指定摘要标记 cmets 时，有没有办法使用 <param> 标记来注意参数是可选的，即。客户端可以提供一个值或空值，例如：<param name="Mime" optional="true">.

谷歌搜索未能为我提供一组属性或允许值的列表。

/// <summary>
/// Sets data associated with instance
/// </summary>
/// <param name="Key">The key defining the data</param>
/// <param name="Value">The data</param>
/// <param name="Mime">The mime type of the data (optional)</param>     <----- Mark as optional

谢谢

【问题讨论】：

曾考虑过重载，但在这个特定示例中我决定反对它。
这个方法是界面的一部分，我觉得为小细节添加额外的重载只会使界面混乱。
我也很好奇在 .NET 4.0 中添加的新可选参数是否支持这种类型的注释（如下所述）。

标签： c# .net xml visual-studio xml-comments

【解决方案1】：

不，你不能。 VS 唯一能识别的属性是name，像这样：

<param name="FileName" >The filename of the file to be loaded.</param>

您唯一能做的就是为您的输出文档设置xsl transform。但这不会对 Intellisense 产生任何影响。

【讨论】：

【解决方案2】：

您应该提供一个省略可选参数的重载：

/// <summary>
/// Sets data associated with the instance using the default media type.
/// </summary>
/// <param name="key">The key defining the data.</param>
/// <param name="value">The data.</param>
public void SetData(object key, object value)
{
    SetData(key, value, null);
}

/// <summary>
/// Sets data associated with the instance using the specified media type.
/// </summary>
/// <param name="key">The key defining the data.</param>
/// <param name="value">The data.</param>
/// <param name="mime">The media type of the data.</param>
public void SetData(object key, object value, string mime)
{
    ...
}

或者，您可以将参数声明为可选：

/// <summary>
/// Sets data associated with the instance.
/// </summary>
/// <param name="key">The key defining the data.</param>
/// <param name="value">The data.</param>
/// <param name="mime">The media type of the data.</param>
public void SetData(object key, object value, string mime = null)
{
    ...
}

【讨论】：

【解决方案3】：

您可以使用<remarks></remarks> 标签。不存在可选参数的特殊标签。

【讨论】：