ScriptDoc: document your Atlas classes

When I was talking at the Journées Académiques last week, someone in the audience asked me about documentation tools for Atlas classes. That was a great question, especially as I had such a tool ready...

This application generates documentation for Atlas client script libraries.

It generates XML documentation files that have the same format as C# documentation files and that can be processed by existing tools such as NDoc.

Documentation is generated from the source code of the classes defined in files and namespaces defined in a project file. The project to use is specified
using the project query string parameter. For example, if you have built the project file myProject.xml in the Projects directory, browsing to
default.aspx?project=myProject will generate the file Output/myProject.xml documentation file.

The tool can work in the absence of specific documentation information in the source code but the usefulness of such documentation will be small.
To include real documentation, you can use the /// comments that are familiar to C# developers with one essential difference: the comments have to be
inside of the class or method definition.

Here's an example of class documentation:

Sys.Data.DataView = function() {
   /// <summary>
   ///   DataView filters its input data through a collection of filters.
   ///   It can also paginate and sort data.
   /// </summary>

   // [... actual definition of the class ...]
}

Here's an example of method documentation:

this.getItem = function(index) {
   /// <summary>
   ///   Gets an item in the filtered data by index.
   /// </summary>
   /// <param name="index">The index in the filtered data of the row to return.</param>
   /// <returns>Null if the row was not found.</returns>

   return _filteredTable ? _filteredTable[index] : null;
}

And finally, here's an example of a property's documentation (notice how the
documentation is on the getter only, not on the setter):

this.get_data = function() {
   /// <summary>
   ///   The data that the view will filter.
   /// </summary>

   return _data;
}
this.set_data = function(data) {
   _data = data;
}

To be able to write the output XML file, the application must have write access to the output directory. For this reason and also because I didn't especially look for possible injection attacks, this application should never be exposed publicly on the Internet. I recommend making it only accessible locally.

One more thing: for all this to work, the application must be installed in an Atlas-enabled application. This means the right web.config, Atlas dll and of course the script files that you wish to document.

You can download the tool (source code included) from this workspace:
http://www.gotdotnet.com/workspaces/workspace.aspx?id=5d6cbdb9-c177-40f2-98db-71ec86a467cc
http://www.codeplex.com/scriptdoc

UPDATE: The 1.0 version, which works with ASP.NET Atlas 1.0 and later and produces data that Sandcastle can use can now be found on Codeplex.