Along with Resharper, the following class was created using a minimum number of keystrokes. Basically, I typed the names of the fields, and shortcut the rest. Consider the following class that I might want to have Xml documentation for:
public class Person
{
private string _firstName;
private string _lastName;
private string _phoneNumber;
private int _age;
public string LastName
{
get { return _lastName; }
set { _lastName = value; }
}
public string PhoneNumber
{
get { return _phoneNumber; }
set { _phoneNumber = value; }
}
public int Age
{
get { return _age; }
set { _age = value; }
}
public string FirstName
{
get { return _firstName; }
set { _firstName = value; }
}
public Person(string firstName, string lastName, string phoneNumber, int age)
{
_firstName = firstName;
_lastName = lastName;
_phoneNumber = phoneNumber;
_age = age;
}
}
I could type all the Xml comments myself, but that would be considerable effort, and there isn’t anything special about this class. Most people could guess what this API does, so why not have a tool help with the Xml comments. I press CTRL + Q (my GhostDoc shortcut key) on each of my properties as well as the constructor, and I immediately have the following:
public class Person
{
private string _firstName;
private string _lastName;
private string _phoneNumber;
private int _age;
/// <summary>
/// Gets or sets the name of the last.
/// </summary>
/// <value>The name of the last.</value>
public string LastName
{
get { return _lastName; }
set { _lastName = value; }
}
/// <summary>
/// Gets or sets the phone number.
/// </summary>
/// <value>The phone number.</value>
public string PhoneNumber
{
get { return _phoneNumber; }
set { _phoneNumber = value; }
}
/// <summary>
/// Gets or sets the age.
/// </summary>
/// <value>The age.</value>
public int Age
{
get { return _age; }
set { _age = value; }
}
/// <summary>
/// Gets or sets the name of the first.
/// </summary>
/// <value>The name of the first.</value>
public string FirstName
{
get { return _firstName; }
set { _firstName = value; }
}
/// <summary>
/// Initializes a new instance of the <see cref=”Person”/> class.
/// </summary>
/// <param name=”firstName”>Name of the first.</param>
/// <param name=”lastName”>Name of the last.</param>
/// <param name=”phoneNumber”>The phone number.</param>
/// <param name=”age”>The age.</param>
public Person(string firstName, string lastName, string phoneNumber, int age)
{
_firstName = firstName;
_lastName = lastName;
_phoneNumber = phoneNumber;
_age = age;
}
}
Most of the work is done. There is no way GhostDoc can read my mind, so I might have to make a few adjustments to the comments, but they are minimal. Note that GhostDoc got confused on firstName and lastName, but that’s understandable. It hits the rest dead-on:
public class Person
{
private string _firstName;
private string _lastName;
private string _phoneNumber;
private int _age;
/// <summary>
/// Gets or sets the last name.
/// </summary>
/// <value>The last name.</value>
public string LastName
{
get { return _lastName; }
set { _lastName = value; }
}
/// <summary>
/// Gets or sets the phone number.
/// </summary>
/// <value>The phone number.</value>
public string PhoneNumber
{
get { return _phoneNumber; }
set { _phoneNumber = value; }
}
/// <summary>
/// Gets or sets the age.
/// </summary>
/// <value>The age.</value>
public int Age
{
get { return _age; }
set { _age = value; }
}
/// <summary>
/// Gets or sets the first name.
/// </summary>
/// <value>The first name.</value>
public string FirstName
{
get { return _firstName; }
set { _firstName = value; }
}
/// <summary>
/// Initializes a new instance of the <see cref=”Person”/> class.
/// </summary>
/// <param name=”firstName”>First name.</param>
/// <param name=”lastName”>Last name.</param>
/// <param name=”phoneNumber”>The phone number.</param>
/// <param name=”age”>The age.</param>
public Person(string firstName, string lastName, string phoneNumber, int age)
{
_firstName = firstName;
_lastName = lastName;
_phoneNumber = phoneNumber;
_age = age;
}
}
The Xml docs are if you intend to build a .chm with NDoc for a distributed project. For in-house stuff, I don’t bother.
Is there really any point documenting the classes if you’re just restating the obvious, it sort of like doing this in code:
// If value is greater than 3
if (value > 3)
{
// Start work
StartWork();
}
It seems like pointless documentation.
Roland,
Thanks for the tip!
Just a quick side note: The “of the” reordering can be customized – if you find out for yourself that the reordering of “name” is something you have to correct in most cases, you can remove “name” from the list of the “of the” words. If you like the reordering in general, but would like to have e.g. “first” and “last” always in front, you can add these to the “of the adjectives”, so
- “firstName” would become “first name”
- “firstItemName” would become “first name of the item”
but also
- “firstSpecialName” would become “first name of the special” (hmm…)
So it there’s always some kind of trade-off
Roland