Effective XML Document with C#, NDoc, Lutz's Documentor and the Microsoft HTML Help Workshop
.JPG)
A lot has been said on this topic, but here's some stuff you might not know.
We use NDoc to document our API. NDoc consumes the XML Documentation files created as a build artifact by the C# compiler.
- Here is the list of recommended XML Documentation tags from Microsoft.
- Here is the extended list of tags supported by NDoc
Most links online that talk about XML Documentation in stop at <summary> and the standard <param> stuff. Method documentation is interesting, but the real meat happens at the top of your Class declarations. That's where most of the prose is in MSDN documentation. Take a look at the Remarks section of the Socket Class in the MSDN Help for example.
To achieve such a rich structure, organize your XML help thusly on the top of each class declaration:
- <Summary>
- <Remarks>
- <Note>(s)
- <Example>(s)
- <Code>
- <SeeAlso>(s)
The XML Comment snippet below, along with NDoc produced the lovely MSDN-style documentation in the picture at right.
The <summary> tag explains the “point” of the class. A sentence or two is fine here.
/// <summary>
/// Encapsulates Thingie and a Connection to Thingie in a Service wrapper.
/// Other Services will be built with this building block.
/// </summary>
The <remarks> tag is where the real prose goes. Use this tag to describe the general use of the class, as well as any notes, gotchas, or significant design or architectural issues.
Note the use of <para> to separate paragraphs. Use <see> to refer to namespaces, classes or methods. If you don’t include the fully qualified namespace, the documenter will assume the current namespace.
/// <remarks>
/// <para>The ThingieService class contains a <see cref="IConnector"/>
/// that is pulled from the named element in the config/ThingieClient.config file. The config file
/// is loaded by <see cref="I"/>.</para>
/// <para>Note that the constructor is private, as your application gets a ThingieService by calling the static <see cref="GetThingieService"/> method.
/// From there, the ThingieService hides the <see cref="IConnector"/> and
/// is the primary interface to Thingie. The ThingieService shouldn't be used directly from an ASP.NET
/// page. Instead, it should be used from either a generated or hand-written proxy.</para>
/// <note type="note">ASP.NET developers should use <see cref="Corillian.Thingie.Security.SiteSecureThing"/> to property register a <see cref="ThingiePrincipal"/> with the system to effectively use the ThingieService.</note>
/// <para>There are two ways to call the <see cref="Execute"/> method.</para>
/// <list type="bullet">
/// <item><term>Pass in an object that implements <see cref="IRequest"/>.
/// The Thingie SessionID and UserID will be retrieved from the <see cref="ThingiePrincipal"/> on the current Thread.</term></item>
/// <item><term>Pass in an object that implements <see cref="IRequest"/> along with the Thingie SessionID and UserID as additional parameters.
/// Use this method if your Thread doesn't already have a ThingiePrincipal. One will be made for you temporarily.</term></item>
/// </list>
/// </remarks>
/// <example>
/// <code>
/// public class BankingExample
/// {
/// protected ThingieService thingie = null;
///
/// public BankingExample()
/// {
/// thingie = ThingieService.GetThingieService("BankingServiceProxy");
/// }
///
/// public virtual SignonResponse Signon(SignonRequest req, string userId, string somethingElse )
/// {
/// string sessionid = thingie.SomethingImportantToTheSession(userId);
/// string r = thingie.Execute(req, sessionid, userId);
/// SignonResponse retVal = SignonResponse.FixUpSomething(r);
/// return retVal;
/// }
/// }
/// </code>
/// </example>
/// <seealso cref="IRequest"/>
/// <seealso cref="IConnector"/>
/// <seealso cref="IConfig"/>
/// <seealso cref="ILoggingService"/>
public class ThingieService....
I also like to use Lutz Roeder's .NET Documentor to write my XML Comments in. It has a split-pane view and a nice right-click menu that let's me see what the documentation will look like AS I TYPE.
Considering that I'd need to recompile the Application AND generate the MSDN documentation, this little tool is a big time saver.
About Scott
Scott Hanselman is a former professor, former Chief Architect in finance, now speaker, consultant, father, diabetic, and Microsoft employee. He is a failed stand-up comic, a cornrower, and a book author.
About Newsletter
