11

When specifying summary tag comments, is there a way with the <param> tag to note that a parameter is optional, ie. the client can supply a value or null, such as: <param name="Mime" optional="true">.

Googling has failed to provide me with a set list of attributes or allowed values. 

/// <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

Thanks

cweston
  • 11,297
  • 19
  • 82
  • 107
  • 2
    Overloading was considered, however I decided against it in this particular example. – cweston Sep 07 '11 at 13:40
  • This method is part of an interface, I felt that adding an additional overload for such as small detail would just clutter the interface. – cweston Sep 07 '11 at 14:15
  • 2
    I was also curious whether this type of commenting was supported with the addition of the new optional parameter available in .NET 4.0 (as mentioned below). – cweston Sep 07 '11 at 14:18

3 Answers3

7

No, you can't. The only attribute being recognized by VS is the name, like that:

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

The only thing that you can do - is to set xsl transform for your output document. But this won't have any effect on Intellisense.

VMAtm
  • 27,943
  • 17
  • 79
  • 125
4

You should provide an overload that omits the optional parameter:

/// <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)
{
    ...
}

Alternatively, you can declare the parameter as optional:

/// <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)
{
    ...
}
dtb
  • 213,145
  • 36
  • 401
  • 431
1

You can use <remarks></remarks> tag. Doesn't exist special tag for optional params.

Kirill Polishchuk
  • 54,804
  • 11
  • 122
  • 125