Visual Studio: Doc Comments that get updated when renaming classes/fields/methods

Question

I have a class (written in C#) with some documentation comments:

/// <summary>
/// Abstract class defining a tolerance-based method for Equals.
/// Tolerance must be defined in a derived class like this:
/// <code>class MyPrec : Precision { private MyPrec() : base(42) {} }</code>
/// (This subclass will have a tolerance of 42.)
/// </summary>
public abstract class Precision
{
    protected readonly double TOL;

    protected Precision(double tol)
    {
        TOL = tol;
    }

    /// <summary>
    /// Checks if two doubles are equal up to numerical tolerance given by TOL.
    /// </summary>
    /// <param name="left">First double.</param>
    /// <param name="right">Second double.</param>
    /// <returns>True if the absolute value of the difference is at most TOL,
    ///          false otherwise.</returns>
    public bool Equals(double left, double right)
    {
        return Math.Abs(left - right) <= TOL;
    }

    /// <summary>
    /// Not Equals.
    /// </summary>
    public bool NotEquals(double left, double right)
    {
        return !Equals(left, right);
    }
}

If I rename the parameter left in the Equals method via Visual Studio's renaming feature, it automatically gets renamed in the documentation comment, too. But it seems that this only works for immediate parameters.

How do I write the documentation comments such that the following words are also updated by Visual Studio when renaming the corresponding class/field/method?

Precision in the code example of the summary comment of the class Precision

    /// <code>class MyPrec : Precision { private MyPrec() : base(42) {} }</code>

TOL in the return comment of the method Equals

/// <returns>True if the absolute value of the difference is at most TOL,

Equals in the summary comment of NotEquals
```
/// Not Equals.
```

I'm using Visual Studio 2015.

I already tried

    /// <returns>True if the absolute value of the difference is at most <paramref name="TOL"/>,

but it does not work. It is no input paramter after all.

Please post your related question as a separate question. – Peter Macej Jul 25 '16 at 17:01 — Peter Macej, Jul 25 '16 at 17:01

score 1 · Accepted Answer · answered Jul 25 '16 at 17:13

Precision, I think this is not possible. The comment inside the <code> tag is a free text.
For TOL and Equals, this is simple. Use the <see> tag when you refer to another code member in your comments. Renaming will be applied to such elements. In your case the comment will be:
```
/// <returns>True if the absolute value of the difference is at most <see cref="TOL"/>,
```

and

    /// Not <see cref="Equals"/>.

Visual Studio: Doc Comments that get updated when renaming classes/fields/methods

1 Answers1