GhostDoc 2.0.0 Released
GhostDoc is a free add-in for Visual Studio that automatically generates XML
documentation comments for C#. Either by using existing documentation inherited
from base classes or implemented interfaces, or by deducing comments from
name and type of e.g. methods, properties or parameters.
- Support for Vista out of the box
- Support for Orcas (tested: Beta 1)
- Better support for generics, more language elements, new rules, new macros
- Download on the GhostDoc Website
- Users of earlier versions: Please read the ReadMe on upgrading!
(The file is contained in the ZIP file)
About this Release
Version 2.0 is the first real feature release for a long time. Originally intended to be a minor update to fix installation problems on Windows Vista (and to be called 1.9.6), it ended up much larger than I had planned. In the second week of April I had the opportunity for almost one week to work exclusively on GhostDoc, so I used the time to implement the features I was missing the most in my everyday, non-GhostDoc-related work. Along the way I was able to implement a few of the external feature requests waiting in my issue tracking database.
What then followed was what could best described as deployment hell, but I must admit that I was being extra ambitious, targeting a simultaneous release of (separate) versions for Visual Studio 2005 and Orcas plus Vista compatibility (which in my case required a little more than simply patching an MSI). Building and testing setups plain sucks, period. No matter how careful you plan things (very carefully), how much automated your build process is (very automated) or how intensely virtual machines are used (very intensely) – the moment you modify a working setup, you’re doomed. There’s always one more typo, one more slight problem; it seems as if you’re never finished.
OK, enough rambling of a tired developer, here’s the good stuff:
What’s New in GhostDoc 2.0.0:
- Added: Support for Visual Studio codename "Orcas". Note that GhostDoc for Visual Studio 2005 and GhostDoc for Visual Studio "Orcas" are released in separate setups and have to be installed into separate folders. Both offer equal functionality and thus share the same configuration file, though. This will stay this way as long as GhostDoc 2.x is released both for 2005 and "Orcas".
- Added: Support for generic methods. The type parameters are now documented using the
<typeparam> tag. For type parameter names starting with 'T' (e.g. "TKey") documentation text is generated (e.g. "Type of the key"), for all other type parameter names the text is left empty. Note that this behavior is currently hard-coded.
- Added: New text generation rules for classes, interfaces and structs (with support for generic type parameters). The default rules generate empty summaries and place the cursor so you can start typing the summary immediately. It is possible to change the summary template to insert e.g. the class name split into individual words, but honestly I don't want to ship GhostDoc with that behavior by default as I didn't find it too helpful. In addition to the default rules, it's also possible to define custom rules (e.g. for classes with a name ending on a specific suffix).
- Added: A new macro
$(End) for specifying the location of the text cursor after the documentation text has been generated.
- Added: A new macro
$(Rule) that inserts the display name of the rule that generated for documentation text. Useful for debugging custom rules, this macro can e.g. be used in the custom text that is added to new doc comments (see the last tab of the GhostDoc configuration dialog).
- Added: A macro of the format
$(%VarName%) inserts the value of the environment variable with the name "VarName" (or an empty string if no variable with that name exists).
- Added: A few language elements are now supported with limited functionality, i.e. without specific rule types (new rule types may be added in future versions, but they didn't have a high priority to be included in 2.0 as the existing functionality already helps a lot):
The cursor is moved inside the summary tag so you can start typing right away. As usual, existing documentation will not be overridden.
- enums - empty summaries for the enum and all of its values
- enum values - empty summary
- events - summary starting with "Occurs when"
- delegates - empty summary
- variables - empty summary
- Added: New method rules:
On a side note, these new rules have been implemented using custom method rules, i.e. using only what was already available in earlier versions of GhostDoc.
- A rule for
- A rule for overloaded operators
- Rules for implicit/explicit conversion operators
- Added: Before upgrading or importing a configuration, it is now possible to quickly create a backup copy by clicking the link in the lower left of the dialog. This is useful especially during an upgrade installation.
- Changed: The experimental support for VB.Net has been disabled in this release. I was pretty tight on my time budget and couldn't spend any time on keeping support for C# and VB.Net in sync.
- Changed: The demo project is no longer installed to a sub-folder of the GhostDoc directory (where it caused problems when working with a non-admin account). Instead, the demo project is now an optional feature with its own setup, suggesting an installation path in the user's Visual Studio project folder.
- Fixed: Error message when installing GhostDoc by double-clicking the MSI file on a Vista system.
- Fixed: When defining custom rules, conditions for method and type names didn't work well with type parameters (generics).
- Fixed: The "Document this" command worked only when the cursor was positioned in a specific way. This has been relaxed, the cursor may now also be positioned on the whitespace before the language element (in the same line as the identifier), or somewhere inside the documentation comment.
Update 2007–05–02: Please guys, please read the instructions on upgrading in the ReadMe!