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.
<?xml version="1.0"?>
<Library>
<Class name="CatalogProvider">
<docs>
<summary>This is a sample class.</summary>
<remarks>
Here are some interesting remarks about the Foo sample class.
</remarks>
<seealso cref="Commerce.Providers.CatalogProviderConfiguration">CatalogProviderConfiguration Class</seealso>
<seealso cref="System.Configuration.Provider.ProviderBase">ProviderBase Class</seealso>
</docs>
<Property name="Instance">
<docs>
<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>
</docs>
</Property>
<Method name="LoadProvider">
<docs>
<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>
</docs>
</Method>
</Class>
</Library>
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.
Rabi--
I have a question.
Am I reading you correctly, you are saying that the documentation comments will NOT reside in the actual source code files as standard XML-based comments but rather they will reside in a separate file?
I have never seen it done it that way and I am wondering is there really is a compelling reason to separate the comments from the source code. I see that you say you want to decouple the comments from the code so that the comments can be updated without the source code. With alldue respect, I find this strange and simply had to ask a question.
After all, isn't it the very point of source code documentation to be updated with the source code itself? That is, the 2 should be coupled and update in sync. No?
Anyway, I just thought I would post some thoughts.
Thank you.
--Mark
Posted by: mkamoski | January 20, 2006 at 10:45 PM
First I am not really talking about source code comments. The documentation is usage information i.e. how do I use a class or method.
The reason to seperate this type information is that it can be modified very rapidly without colliding with development since the documentation might be done by someone other than the developer. While you do have to compile to get the XML file for the assembly it can be done using a skeleton of the class. It also is easier to swap around XML files rather than source code. I know that the XML documentation might be wrong but a malcious person could not do much harm. Ok at worse they can embedded some links but before I added the documentation to my set of documentaion I would check for this. It is much easier to check for this in XML than in actual source code.
So no I am not advocating seperating the source code comments from the code. I am advocating seperating the usage documentation from the code. You are very much right about not wanting to do that with source code comments so the source code is documented.
Posted by: Rabi Satter | January 21, 2006 at 11:08 AM