CODEWITHSUNDEEP
c#code-documentation
Wouter Vandenputte
Wouter Vandenputte

Reputation: 526

C# Documentation: refer to other property

Suppose I have this class

public sealed class Person 
{
  public string FirstName { get; set; }
  public string LastName { get; set; }

  public string DisplayName => $"{FirstName} {LastName}";
}

And I want to document the DisplayName property.

/// <summary>
/// A space seperated string of the FirstName and LastName
/// </summary>
public string DisplayName => $"{FirstName} {LastName}";

But my problem now is, what if for example I rename the property LastName to FamilyName. My code would ofcourse still compile but my documentation would refer to a non existing property.

Is there somehow a way to refer in the property DisplayName to the actual property LastName like this pseudo syntax.

/// <summary>
/// A space seperated string of the <prop=FirstName> and <prop=LastName>
/// </summary>

such that refactoring my code would also refactor the documentation or that the compiler would at least give a warning or maybe an error?

Upvotes: 1

Views: 625

Answers (1)

MakePeaceGreatAgain
MakePeaceGreatAgain

Reputation: 37000

Use a <see>-tag with a code-reference-attribute (cref):

/// <summary>
/// A space seperated string of the <see cref="FirstName" /> and <see cref="LastName" />
/// </summary>

You can also reference members of other classes by qualifying them appropriately, e.g.

/// <summary>
/// A space seperated string of the <see cref="AnotherClass.FirstName" /> and <see cref="MyClass.LastName" />
/// </summary>

or also a method:

/// <summary>
/// A space seperated string of the <see cref="MyMethod" /> and <see cref="MethodWithOverloads(string, int, Type)" />
/// </summary>

Upvotes: 9

Related Questions