C# method parameter XML-documentation issue

Question

Assume, i have a method which parameters are classes with already defined documentation:

/// <summary>
///     Get criterion from table.
/// </summary>
/// <param name="plySide"></param>
/// <param name="criterionType"></param>
/// <returns></returns>
public Criterion GetCriterion(PlySide plySide, CriterionType criterionType)
{
   // some code
}

PlySide class has it's own xml-documentation:

/// <summary>
///     Sides of monoply.
/// </summary>
public enum PlySide
{
   // some code
}

As you can see in GetCriterion method i didn't define any doc for the plySide param tag. My question is should i duplicate description of a parameter or should i remove param tags?

I wouldn't consider it to be duplicated as the developer should always go back to the corresponding file to look at the comments if not — Praveen
– Praveen, Commented Jun 27, 2017 at 8:22

Damien_The_Unbeliever · Accepted Answer · 2017-06-27 08:40:33Z

1

The PlySide documentation will describe what the type is.

The plySide documentation should describe what role that parameter plays within the GetCriterion method.

Those will usually be subtly (or not so subtly) different.

answered Jun 27, 2017 at 8:40

Damien_The_Unbeliever

241k28 gold badges358 silver badges470 bronze badges

Sign up to request clarification or add additional context in comments.

Comments

Romano Zumbé · Accepted Answer · 2017-06-27 08:28:07Z

1

You shouldn't duplicate it but give a context aware description of the parameter. In your case it could be something like this (perhaps it's toally wrong, but I don't know the implementation and intention of your method):

/// <summary>
///     Get criterion from table.
/// </summary>
/// <param name="plySide">Monopoly side to get criterion for</param>
/// <param name="criterionType">Criterion to get for the given monopoly side</param>
/// <returns></returns>
public Criterion GetCriterion(PlySide plySide, CriterionType criterionType)
{
   // some code
}

answered Jun 27, 2017 at 8:28

Romano Zumbé

8,1495 gold badges37 silver badges61 bronze badges

Collectives™ on Stack Overflow

C# method parameter XML-documentation issue

2 Answers 2

Comments

Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

Comments

Comments

Your Answer

Sign up or log in

Post as a guest

Related