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

Question

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.

I think you might be mixing things up - why does the caller of MyMethod need the "very detailed description" of myField? If you generate source code documentation via e.g. SandCastle, then you can easily navigate the documentation using the links created from cref. Alternatively you could actually simply copy the description - what would your ideal behaviour be like? Can you describe the steps you'd like to be able to do with the desired outcome? And not entirely sure that I got what your aim is. — Gorgsenegger
– Gorgsenegger, Commented Nov 23, 2013 at 19:56
Does this answer your question? Can I reference property comments in constructor comments? — Heriberto Lugo
– Heriberto Lugo, Commented Apr 30, 2024 at 14:54

Jason Williams · Accepted Answer · 2013-11-23 20:15:36Z

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)

Collectives™ on Stack Overflow

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

1 Answer 1

Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related