Commenting Style (i.e. Javadocing C# Version) - (Java Developer Learning C#)

Question

I'm finishing up some of my first C# classes and even though the original code I inherited is completely void of comments, I always put javadoc comments on my methods when I was writing java and my code currently looks strange without those blocks.

I normally formatted my comments by using the "Insert JavaDoc" command in Eclipse, which simply laid out the template and pulled in the parameters, method name, etc...from the method the command was run on. Then I could add more detail from there.

Is there a similar command in Visual Studio 2008? I couldn't find one when I was poking around the menus. Additionally, is there a standard convention of commenting style (similar to JavaDoc) that is used in the C# world?

Answer 1

Type three forward slashes before any method:

///

This will generate an XML comment block.

Answer 2

If you type three forward slashes "///" before a method in Visual Studio, it will automatically create a simple template for you to comment methods. (It will create fields for you to comment on parameters and return values, as well.) I think this is nice because it's quick and simple, but you may want something more in-depth.

Answer 3

In C#, if you enter three slashes on top of what you want to comment it will automatically insert the appropriate text for the target.

It will include a summary, parameters (if any), return (if any), etc.

///

You can then use something like NDoc to take those comments and build API documentation out of it.

Answer 4

http://msdn.microsoft.com/en-us/magazine/cc302121.aspx

The entire feature is called xml-doc, you can google lots of examples.

Answer 5

If you type /// the IDE editor will automatically generate an empty XML comment for you.

This:

///
public QName(String qName, XmlNode contextNode) {

Becomes this:

/// <summary>
/// 
/// </summary>
/// <param name="qName"></param>
/// <param name="contextNode"></param>
public QName(String qName, XmlNode contextNode) {

If your method throws any exceptions you'll have to manually add tags since .NET does not have declared exceptions. Final comment:

/// <summary>Creates a new QName from a string with the format
/// <c>prefix:local-name</c> or <c>local-name</c>.</summary>
/// 
/// <param name="qName">A QName string.</param>
/// <param name="contextNode">An XML node from which to lookup the namespace
/// prefix, or <c>null</c>.</param>
/// 
/// <exception cref="XmlInvalidPrefixException">Thrown if the prefix cannot be
/// resolved from the lookup node. If <paramref name="contextNode"/> is
/// <c>null</c>, then the only prefix that can be resolved is <c>xml</c>.
/// </exception>
public QName(String qName, XmlNode contextNode) {

Answer 6

There's a free add-in for Visual Studio, GhostDoc, that will help you create the basic structure for C# XML documentation, providing a little more than /// will get you from Visual Studio itself.