[If you’re impatient then check out the image here to jump straight to the reason behind this post.]
When Microsoft first declared there intent to include support for comments within the C# language I was overjoyed. I was so taken with the idea that I wrote a VB6 add-in that would parse VB6 source comments prefixed by ‘/ and convert them into a HTML page which documents the class. Importantly it also provided a real-time preview window for the current method/property.
As it turned out when .NET was finally released I landed a job coding in VB.NET rather than C#. There were a couple of freeware tools around that would allow the XML documentation files to be produced from VB.NET source code. They were OK but it really wasn’t the same as having the compiler validate comment references. Also most of the tools we tried were a little flaky and prone to crashing every now and then.
Jumping ahead a few years and I’m using C# with Visual Studio 2005 on a large scale project. On this project I was responsible for writing a lot of architecture and doing my best to make sure it was documented. We used NDoc to produce MSDN style Help via MSBuild and our continuous integration engine (CruiseControl.NET). We also had to produce a script that would correctly register the generated v2 Help file to have it integrate seamlessly with the Visual Studio documentation. Setting this up was tricky. It required us to debug and fix the latest NDoc build to properly support generics, use another third party tool to generate the required Help registration goo, write custom NDoc tags for inserting images (like class diagrams) and creating FAQ indexes etc. It would also take about an hour to run (over our 40+ project solution).
But NDoc is dead!
Yes, but as everyone knows Sandcastle lives! The first few drops of Sandcastle were really quite scary. Config files here there and everywhere, write your own scripts to produce the end result. But whilst Microsoft were concentrating hard on getting the fundamental engine right the community came to the rescue with Sandcastle Help File Builder (SHFB). A full featured, easy to use GUI to produce Help v1, v2 and HTML documentation using the Sandcastle engine. The recent builds of Sandcastle coupled with SHFB and we’re finally back (in fact slightly ahead) of where NDoc left off. The SHFB has even been built to look and feel just like the NDoc GUI – nice!
Some HTML v1 output from Sandcastle using SHFB.
Source Comments are ugly
However, having had a chance to write a fair amount of source comments on this particular VS2005 project, one thing became obvious. Improving the quality of the externally viewed documentation (e.g. in dexplore, or HTLP Help Viewer) had a directly negative effect on the readability of the same documentation within the source files (e.g. Visual Studio).
In other words – adding more markup to the source comments made them harder to read in Visual Studio. Yet I want the both of best worlds. I want to be able to produce useful documentation integrated with MSDN but at the same time I want those comments to be easily read by the developer when they are right there in the source.
So what’s the solution?
Well – back in those Visual Studio 2005 days I used to use a little tool called CR_Documentor which was written as a DXCore add-in. This provided a real-time preview window of what your source comments would look like once marked-up. This was really useful as there was nothing more annoying that doing a whole bunch of source comments only to find the next day (after the nightly documentation was produced) I had made some silly error with my markup causing corrupt, incomplete or missing documentation. Admittedly the build I was using used to struggle keeping up with some of the really large namespace documentation (e.g. 500+ lines), but it did a good job for the small stuff.
Configuration settings for CR_Documentor.
But please Microsoft, I want more!
What I really want is source comment markup integrated in the Visual Studio editor. When I’m browsing source code I don’t want to see angle brackets and tags all over the place. I want to see clearly readable documentation. When I want to edit the source comments then you can show me the angle brackets. Or better yet – given only a limited set of documentation and standard HTML tags are supported – why should I ever need to see the tags? Give me a limited document editor with a set of extendable “regions” and some basic bold/italic etc. formatting. (Click the image below to see in its full glory what could be a preview of Dev10).
An impression of what source code comment viewing could be like in Visual Studio.
Some features of the new inline WYSIWYG source comment editor:
- Comments can be collapsed completely, or to a single line (as per existing region style collapse) using the expand collapse arrow to the left of the class/member. (Not sure how the arrow does a three state collapse – but hey why not?)
- Comment sections can each be collapsed to the heading as per MSDN comments.
- Default collapse settings for comments are configurable via Visual Studio settings.
- It should look nicer than my hacked “Frankenstein” screenshot which is more or less just overlaying the Sandcastle output over a Visual Studio editing window. In particular the comments should be de-emphasized.
- Hmm… what else?
Sandcastle – Microsoft’s source code documentation engine
Sandcastle Help File Builder – NDoc-like GUI for Sandcastle
GhostDoc – does a “spooky” job of commenting your code for you.
CR_Documentor – real-time preview window of source comments marked up
XML Documentation Comments Guide – explains the various comment tags for VS 2003, 2005, NDoc and Sandcastle