C# – XML documentation parameter warnings (CS1571, CS1572, CS1573)

When you’re using XML documentation comments in your code, eventually the comments will get out of sync with the code. This is especially true for method parameters, which are documented by <param> tags. When you add, delete, or rename a parameter manually, it’s easy to forget to update the <param> tags. Fortunately, the compiler detects this and shows warnings. It will only show these warnings if:

I’ll show examples of these warnings and how to fix them.

CS1573 Parameter ‘X’ has no matching param tag in the XML comment (but other parameters do)

Warning CS1573 means there’s a missing <param> tag for one of the method parameters. This usually happens when you add a new parameter (or rename one manually) and forget to update the XML documentation.

Here’s a example. Notice it’s missing the <param> tag for the int quantity parameter:

/// <summary> /// Processes Order for specified product /// </summary> /// <param name="productCode">4-digit unique product identifier</param> public void ProcessOrder(int productCode, int quantity)
Code language: C# (cs)

To fix this, add the missing <param> tag:

/// <summary> /// <summary> /// Processes Order for specified product /// </summary> /// <param name="productCode">4-digit unique product identifier</param> /// <param name="quantity">how many units of the product to order</param> public void ProcessOrder(int productCode, int quantity)
Code language: C# (cs)

CS1571 XML comment has a duplicate param tag

Warning CS1571 means there are multiple <param> tags with the same name. This usually happens when you add a method parameter, then copy and paste an existing <param> tag but forget to change the name. This is often accompanied by the CS1573 Parameter has no matching param tag warning.

Here’s an example. Notice there are two <param> tags for productCode:

/// <summary> /// Processes Order for specified product /// </summary> /// <param name="productCode">4-digit unique product identifier</param> /// <param name="productCode">how many units of the product to order</param> public void ProcessOrder(int productCode, int quantity)
Code language: C# (cs)

To fix this, update one of the <param> tag names to match the right parameter:

/// <summary> /// Processes Order for specified product /// </summary> /// <param name="productCode">4-digit unique product identifier</param> /// <param name="quantity">how many units of the product to order</param> public void ProcessOrder(int productCode, int quantity)
Code language: C# (cs)

Or if it’s really just a duplicate <param> tag, then delete it.

CS1572 XML comment has a param tag for ‘X’, but there is no parameter by that name

Warning CS1572 means there’s a <param> tag with a name that doesn’t match a method parameter. This usually happens when you delete a method parameter (or rename one manually) and forget to update the <param> tags. This is sometimes accompanied by the CS1573 Parameter has no matching param tag warning.

Here’s an example. Let’s say you had a method parameter called unitPrice, which deleted, but forgot to remove the associated <param> tag:

/// <summary> /// Processes Order for specified product /// </summary> /// <param name="productCode">4-digit unique product identifier</param> /// <param name="quantity">how many units of the product to order</param> /// <param name="unitPrice">dollar amount each unit sells for</param> public void ProcessOrder(int productCode, int quantity)
Code language: C# (cs)

To fix this, delete the extra <param> tag that’s no longer needed.

Here’s another example. Let’s say you manually renamed the method parameter quantity to qty and forgot to update the <param> tag name:

/// <summary> /// Processes Order for specified product /// </summary> /// <param name="productCode">4-digit unique product identifier</param> /// <param name="quantity">how many units of the product to order</param> public void ProcessOrder(int productCode, int qty)
Code language: C# (cs)

Note: This will have both the CS1572 and CS1573 warnings.

To fix this, update the <param> tag name to match the qty parameter:

/// <summary> /// Processes Order for specified product /// </summary> /// <param name="productCode">4-digit unique product identifier</param> /// <param name="qty">how many units of the product to order</param> public void ProcessOrder(int productCode, int qty)
Code language: C# (cs)

Leave a Comment