CODEWITHSUNDEEP
c#xmlcomments
MaxxAMillion
MaxxAMillion

Reputation: 128

C# XML Comments - Can I refer to another XML comment elsewhere?

I am documenting a C# application and ran into the following nuisance. I have commented a field, where it is defined: 

/// <summary>
/// My very detailed description of this field.
/// </summary>
public float myField;

But elsewhere, I reference this field:

///<summary>
/// Modifies the value of <see cref="myField">. 
///</summary>
public void MyMethod()
{
    ...
}

The problem is that a user calling MyMethod() will have to then go to the definition of myField to see what it actually is. It would be much better if I could copy the content of the summary tag from myField into the description for MyMethod() directly.

Is this supported? Is there a good alternative?

Thanks in advance.

Upvotes: 3

Views: 1274

Answers (1)

Jason Williams
Jason Williams

Reputation: 57892

I'm afraid there's not much you can do about this situation.

Your main options are to not document it at all (not recommended!), to refer to it (a hassle for the end user), or to duplicate or re-state the documentation (a hassle for you).

In this case I'd usually write a brief description that reminds the end user what the variable is for, without necessarily duplicating the entire detailed description, e.g. Modifies the value of <see cref="myField">, which sets the speed of the doodad.

Alternatively, if you would like a way to automate duplicating the original documentation, I've written an add that you could try to see if it suits your needs - Atomineer Pro Documentation. It's a tool to create and update documentation comments, and it tries to duplicate useful documentation from other places in your class or base classes when it can.

For example, if you define a property like this:

/// <summary> Speed of the doodad in m/s, in the range 0.0 - 3.7 </summary>
double DoodadSpeed { get; set; }

...and then you write a method in the same class which has a parameter with a matching name:

void SetNewSpeed(double doodadSpeed)
{
}

... then Atomineer will automatically pick up the description of the like-named property when it documents the parameter, giving you something like:

/// <param name="doodadSpeed"> Speed of the doodad in m/s, in the range 0.0 - 3.7 </param>

For this to work you need to use unique names for each unique value (member, property, parameter) that your class uses so that this approach will work. And of course, it won't work if the name doesn't match, e.g in these cases it wouldn't help you:

SetNewSpeed(int newSpeed) { }
ModifyDoodadSpeedInSomeWay() { }

(so it may not help in the specific example you've posted, as there is no obvious link between the method and the member variable - but I'm not aware of anything that can help to automate that case for you)

Upvotes: 2

Related Questions