Reference Documentation

Wed, 08 Dec 2010 21:02:00 -0500

In the November edition of MSDN Magazine, Peter Gruenbaum explains how to write good reference documentation for APIs in his article titled “A Coder’s Guide to Writing API Documentation”.

My attention was particularly drawn to Figures 2 and 3, which explain how to comment while maintaining consistency throughout the API. I have reproduced them here:

Figure 2: Reference Documentation Style

Type	Guideline	Examples
Class	Start with a word like “Represents”	“Represents a user’s photo album.”
Methods and functions	Start with a verb	“Returns the number of contacts for the specified area.” “Pauses the video.”
Properties	Use a noun or start with verbs such as “Gets” or “Gets and sets”	“The user’s tasks.” “Gets and sets a collection of the user’s tasks.”
Events	Start with a phrase such as “Raised when” or “Occurs when”	“Raised when the response from server is received.”
XML elements	Use a noun-based phrase	“The city’s postal code.”
Boolean values	For Boolean properties, start with “Indicates whether”; for Boolean return values on methods and functions, start with “Returns whether”	“Indicates whether the control is visible.” “Returns whether two regions intersect.”

Figure 3: Reference Documentation Example

Comments on Gabriel Mongeon

Reference Documentation