Question

What is the recommended way to document the parameters and return of a Func property on a class in c#
e.g.

public class Test
{
    /// <summary>
    /// A description of what AFunc is for.
    /// </summary>
    /// <remarks>
    /// Should I document the parameters and return here or somewhere else?
    /// </remarks>
    public Func<object, string[], bool> AFunc { get; set; }
}

Intellisense in Visual Studio 2010 doesn’t offer the param or return tags on a property like it does for methods; would those still be the most appropriate tags to use though?

Edit:

Since asking this I’ve spotted in some of the xml-documentation on msdn that any valid xml can be used to tag, so my thinking now is more so to either simply use the param and return tags; or to use custom tags and decide on appropriate naming?

Answer 1

Rather than depending on code documentation, I’d recommend starting with making your code more “end developer” friendly. Consider changing the return type to a friendly-named delegate.

http://msdn.microsoft.com/en-us/library/ms173171(v=vs.100).aspx

To start with, that will make your code more self explanatory. You can then use code documentation to explain the purpose of the returned value rather than trying to explain the type of returned value.