Scott Hanselman

UEX = User Education and Generating <devdoc>

March 5, '04 Comments [4] Posted in NUnit | NCover | Nant | XML
Sponsored By

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. I am a failed stand-up comic, a cornrower, and a book author.

facebook twitter subscribe
About   Newsletter
Sponsored By
Hosting By
Dedicated Windows Server Hosting by ORCS Web
Friday, March 05, 2004 8:43:40 AM UTC
Thanks for that. I've been doing similar stuff with Doxygen and unmanaged C++, and intended to find out whether NDoc supported it (http://blogs.geekdojo.net/pdbartlett/archive/2004/01/07/542.aspx), but in 2 months have not quite gotten around to digging...
Friday, March 05, 2004 4:48:04 PM UTC
Thanks! Being one of the main developers on this block, and a big pusher of this style, I was happy we could do this and plan on having more of our blocks be consistent in this manner. Thanks for the feedback!

scott
Friday, March 05, 2004 5:03:42 PM UTC
What the UEX format needs is a tool (and MS must have one internally). I started playing with Word 2003's XSLT capabilities to translate UEX into WordML, and then back to UEX when you save so you could have WYSIWYG editing. I got the basic opening stylesheet working, enough to convince myself that it is possible, (but not fun). If anyone knows of a tool to manage these UEX files, I'd love to know about it. Externalizing the comments in UEX has a few advantages, 1) you don't need to give your source code to your technical writers if you wanted help writing GOOD documentation, 2) If you are in a code-freeze stage you can continue to document without having to touch your source code, and 3) translating help files into multiple languages should be much easier by just swapping uex's at compile time.
Thursday, April 14, 2005 7:26:15 AM UTC
This all looks very useful and I'd love to use it, except I've got no idea where Visual Studio is looking for the file.

Anybody got any ideas where these relative paths are relative to? and how to change it? I don't want to end up having to use absolute paths.
Comments are closed.

Disclaimer: The opinions expressed herein are my own personal opinions and do not represent my employer's view in any way.