Scott Hanselman

I was poking around in the Authorization and Profile Application Block and noticed what nice documentation it has.  I'm a HUGE fan of NDoc, and we build a great deal of documentation with it during the automated build process. (The goal: NAnt -> NUnit -> NCover -> NDoc)

Lots of folks know the basics about XML Documentation in C# but usually only take it this far:

   /// <summary>
   /// The entry point for the application.
   /// </summary>
   /// <param name="args"> A list of command line arguments</param>
   public static int Main(String[] args)
   {
       return 0;
   }

However there's a lot more cool stuff/tags beyond summary and param that can be done with XML Documentation.  Also adding LOTS of rich documentation to your source code can make the files unruly and end up containing more prose then code. 

So, you can instead add your documentaiton like this:

   /// <include file="doc\Main.uex" path='docs/doc[@for="MyNamespace.Main"]/*'></include>
   public static int Main(String[] args)
   {
       return 0;
   }

and then you'd have a file called Main.uex in your doc directory:

<docs>
    <doc for="MyNamespace.Main">
        <summary>
            <para>Get the whatever from the <paramref name="whateverElse"/> for the <paramref name="whatever"/>.</para>
        </summary>
        <param name="whateverElse">
            <para>The section to retrieve the whatever.</para>
        </param>
        <param name="whatever">
            <para>The whatever to retrieve.</para>
        </param>
        <returns>
            <para>The <see cref="SomeClassName"/> for the given name.</para>
        </returns>
        <exception cref="SomeException">
            <para>An error occurred while performing the operation.</para>
        </exception>
        <remarks>
            <para>Here is some text about something.</para>
            Here is the config section in the configuration file:
            <code>
            ...
            &lt;section name="mySection" type="MyConfigHandler,MyAssembly,Version=1.0.0.0,Culture=neutral,PublicKeyToken=null" /&gt;
            ...
            </code>
            Here is the code that do something.
            <code> 
                using System;
                class MyNamespace {
                private String whatever;
                }
            </code>
        </remarks>
    </doc>
</docs>

Another interesting thing is the <devdoc> tag, which is apparently to indicate documentation that originates from the developer and not the documentation team.   

I think I'll be a lot more likely to include rich documentation for Frameworks we design if I have more room to add code samples and remarks.  Very cool.  You can find lots of great example of this kind of file in the newer Application Blocks, or the Rotor Source Code.  I recommend the former. 

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

Hosting By