Roland Weigelt

Born to Code

News

.NET related Links

Archives

GhostDoc 2.0.0 Released

<summary>
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.
</summary>

20070501_GhostDocQuick Facts

  • 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):
    • 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
    The cursor is moved inside the summary tag so you can start typing right away. As usual, existing documentation will not be overridden.
  • Added: New method rules:
    • A rule for Dispose(bool disposing)
    • A rule for overloaded operators
    • Rules for implicit/explicit conversion operators
    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.
  • 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!

Comments

Jansen said:

Fantastic work! My team has been waiting for these new features for ages.

# May 1, 2007 11:42 PM

ArnieZ said:

Great! I look forward to using the new features.

# May 2, 2007 6:06 AM

m4h4r4 said:

I've been using this add-in since a long time ago and I really love it.

Thanks for the great and hard work!

# May 2, 2007 9:00 AM

Patrick said:

"The experimental support for VB.Net has been disabled in this release."

Just writting to support the use of VB.Net commenting. I've been using it for awhile. I would hate to see this feature left behind.

# May 2, 2007 10:38 AM

Henk van Es said:

Love this tool!

One remark, had to uninstall 1.9.5. on my Vista machine first, otherwise I got an error installing. On a w2k3 machine the 2.0 installer just replaced the 1.9.5 :)

again, great tool!

# May 2, 2007 12:27 PM

WeigeltRo said:

Henk wrote:

> One remark, had to uninstall 1.9.5. on my Vista machine first, otherwise I got an error installing.

> On a w2k3 machine the 2.0 installer just replaced the 1.9.5 :)

No offense, but did you read the instructions on upgrading in the ReadMe inside the ZIP file?

# May 2, 2007 12:49 PM

Henk said:

> No offense, but did you read the instructions on upgrading in the ReadMe inside the ZIP file?

Oops, no, was to enthousastic to upgrade right away!

sorry!

# May 3, 2007 1:27 AM

Oskar Austegard said:

Great!  Thanks, Roland. I've been digging GhostDoc since it was a wee little beta, nice to see it all grown up.

Another tool to add to our standard developer vpc build...

# May 3, 2007 8:19 AM

DaRage said:

Great plugin i use it everyday... way to go!!

# May 9, 2007 11:41 AM

Triforce said:

GhostDoc is a great tool, I'm just very disappointed that the experimental support for VB.NET is disabled.  This makes it pretty much useless to me, as we are doing 90% of our development in VB.NET.

I got so excited when I heard about the new version and immediately upgraded, then once I realized this had to uninstall and go back to version 1.9.5  I would love to see a version of GhostDoc that has not experimental, but FULL VB.NET support!  Seems like this would be more valuable to the product rather than adding more features.  Just my 2 cents.

# May 10, 2007 5:58 PM

Danny McNaught said:

"The experimental support for VB.Net has been disabled in this release."

Just writting to support the use of VB.Net commenting. I've been using it for awhile. I would hate to see this feature left behind.

Seconded!

# May 18, 2007 1:30 PM

jafin said:

Awesome work! I wasn't aware of the 2.0 release until today.  Thanks for the magical update!

# May 21, 2007 7:38 PM

Mike Lyons said:

Great to see that events are now included.

Sad to see the support for VB.Net turned off for the moment. Unfortunately it also effects our C# development as it means we have to stick with the older version.

Oh well. I'm looking forward to a possible release in future which supports VB.Net again.

# May 22, 2007 1:16 AM

WeigeltRo said:

Version 1.9.5 can be downloaded here:

www.roland-weigelt.de/.../download05.php

# May 23, 2007 6:59 AM

Joe said:

I also hate to see VB support is disabled in this great release.

Do you have plan to enable VB support again in the future?

# May 26, 2007 10:01 AM

Pierre Mengal said:

I can't wait to pay for this!

You deserve it.

# June 5, 2007 10:29 AM

WeigeltRo said:

Hi Michael,

regarding your feature request: weblogs.asp.net/.../400951.aspx ;-)

regarding your suggestion concerning the Paypal button: I aready had thought about that in the past, but - being a cautious person - I first asked local authorities about the legal implications (asking Paypal didn't produce any useful information, BTW).

While the Finanzamt (IRS) said that they dont't care as people are giving money to me as a gift, the Gewerbeamt (responsible for business licenses) said that they in turn didn't care about the voluntary nature of the donation. The problem is that I'm offering some sort of a service and people are able to pay for it so this implies I'm offering GhostDoc to make money. Getting a business license just to have a Paypal button on my website was simply too much for me, so I skipped that idea. And before anybody's asking: No, I don't have any plans of founding a business and really going commercial with GhostDoc.

# June 7, 2007 11:10 AM