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>
...
<section
name="mySection" type="MyConfigHandler,MyAssembly,Version=1.0.0.0,Culture=neutral,PublicKeyToken=null"
/>
...
</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.
Hosting By
or, if you like Pepsi, here: 
.
