TypeName | ElementParameterDocumentationMustMatchElementParameters |
CheckId | SA1612 |
Category | Documentation Rules |
Cause
The documentation describing the parameters to a C# method, constructor, delegate or indexer element does not match the actual parameters on the element.
Rule Description
C# syntax provides a mechanism for inserting documentation for classes and elements directly into the code, through the use of Xml documentation headers. For an introduction to these headers and a description of the header syntax, see the following article: http://msdn.microsoft.com/en-us/magazine/cc302121.aspx.
A violation of this rule occurs if the documentation for an element’s parameters does not match the actual parameters on the element, or if the parameter documentation is not listed in the same order as the element’s parameters.
How to Fix Violations
To fix a violation of this rule, correct the parameter documentation so that the <param> tags in the documentation appear in the same order as the element’s parameters, and so that there is one <param> tag for each parameter on the element.
The following example shows a method with a valid documentation header:
/// <summary>
/// Joins a first name and a last name together into a single string.
/// </summary>
/// <param name="firstName">The first name to join.</param>
/// <param name="lastName">The last name to join.</param>
/// <returns>The joined names.</returns>
public string JoinNames(string firstName, string lastName)
{
return firstName + " " + lastName;
}