So while waiting for the next version of CSK I decided to get a jump on what I figure will be the most asked for item. Where's the documentation? Hopefully the development team is reading this.
The first item for my impromptu CSK Documentation project was what to use for documenting. The answer as you can probably guess is NDoc. This open source tool uses reflection and XML documentation emitted by the .Net compiler to build a variety of documents from Help to HTML documentation.
I am not going to make this an NDoc tutorial since that is not what I am after. If you want that then use Google and pick an entry. However, I do need to work out the best approach to building the documentation. After doing research, I decided the best approach would be to have a seperate XML file contain the documentation. This would make it easier for the documentation to be updated without the source code.
Fortunately, NDoc fully supports such an approach using XPath notation and an include tag.
/// <include path="//Method[@name="ProductsSearch"]/docs/*" file="CatalogProvider.xml"></include>
static CatalogProvider LoadProvider()
The include tag has two parts. An XPath notation stating that for the method below look for a Method node named LoadProvider and grab all its nodes. The second part is the name of the file containing the XML. In this case I decide to use an XML file per source code file. So CatalogProvider.cs has a matching CatalogProvider.xml containing the various additional documentation like summary, remarks, seealso, parameters etc.
<summary>This is a sample class.</summary>
Here are some interesting remarks about the Foo sample class.
<seealso cref="Commerce.Providers.CatalogProviderConfiguration">CatalogProviderConfiguration Class</seealso>
<seealso cref="System.Configuration.Provider.ProviderBase">ProviderBase Class</seealso>
<summary>The default maximum number of iterations to search.</summary>
<value>The default maximum number of iterations to search.</value>
<remarks>The default maximum number of iterations to search is 500.</remarks>
<summary>Attempts to solve the function, using the specified max. number of iterations.</summary>
<remarks>Attempts to solve the function, using the specified max. number of iterations.</remarks>
The next step is to make sure that the XML documentation is outputted during compilation. This is accomplished by changing the project build properties. You can see by clicking on the picture to the left of this.
The last step is to use NDoc to build the actual documentation. This involved building an NDoc project. I then point it at the assemblies I want to document and a variety of properties including the type of documentation HTML or Help and the style of documentation. I decided to build HTML and upload the files to my website. This way as I make progress people can use the documentation. And more importantly if you would like to help then pick a file, build the XML file and send it to me and pretty soon the whole CSK will be documented.
Here is a zip of the latest XML files.