CODEWITHSUNDEEP
c#propertiesfuncxml-documentation
Alternator
Alternator

Reputation: 164

What is the recommended way to create xml documentation for a Func property

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?

Upvotes: 3

Views: 284

Answers (2)

Paul Fleming
Paul Fleming

Reputation: 24526

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.

Upvotes: 4

Jason Williams
Jason Williams

Reputation: 57902

Properties don't use param, as they don't take parameters - you need to use typeparam for generic parameters. Instead of returns, use value.

Upvotes: 0

Related Questions