2009-03-20

A tip for writing Xml comments in Csharp

There is something called xml comments in the dotnet world.

It looks something like

/// <summary>
///
/// </summary>
/// <param name="name"></param>
/// <returns></returns>
public User FindUser( string name )
{...


The trick here is to write the comments on the very first line. Like:

/// <summary>This method finds and returns a User by its name.
/// </summary>
/// <param name="name"></param>
/// <returns></returns>
public User FindUser( string name )
{...


When the code is folded it then looks like

/// <summary>This method finds and returns a User by its name. ...
public User FindUser( string name )...


Visual Studio "suggests" writing the comments on line two, like

/// <summary>
/// This method finds and returns a User by its name.
/// </summary>
/// <param name="name"></param>
/// <returns></returns>
public User FindUser( string name )
{...


but then after folding it looks like

/// <summary> ...
public User FindUser( string name )...


(this is not a problem in vbnet)

No comments: