Question

I am just starting to look at the C# documentation standards. Here’s a method that I have:

/// <summary>
/// Reformats a key in x.x format to 0x0x format
/// </summary>
/// <param name="dotFormatRowKey">key in ##.## format</param>
public static string DotFormatToRowKey(this string dotFormatRowKey) 
{

    if (! Regex.IsMatch(dotFormatRowKey, @"\d+\.\d+"))
       throw new ArgumentException("Expected ##.##, was " + dotFormatRowKey);

    var splits = dotFormatRowKey.Split('.')
                 .Select(x => String.Format("{0:d2}", Int32.Parse(x)))
                 .ToList();
    var joined = String.Join(String.Empty, splits.ToArray())

    return joined;
}

Can someone give me advice on how I should document the input and return parameters for this method. Also when I do this will the documented comments be available to a person if they use VS2010 intellisense?

Answer 1

As for how you should document the parameters: i think thats pretty subjective but the way you did it now looks ok to me. Altho you could maybe change your return variable joined into something more verbose, like "keyFormattedString" or something.

as for the second part of your question:

Also when I do this will the documented comments be available to a
person if they use VS2010 intellisense?

Quote taken from msdn:

Extension methods are only in scope when you explicitly import the
namespace into your source code with a using directive.

If the method is inside some class in a class library, then they will have to reference that library into their current solution, in order to use/see the method and documented comments. You can basically make a new class library with all your extension methods in it, and then import that DLL to whatever solution you’re working on.

Let’s say that you have a class library, then you simply add

using ExtensionMethodsLib; // or whatever you'll call it

to your using statements, on whatever page you might need it.

Extension methods (msdn)