Roland Weigelt : GhostDoc

Upgrading from “Weigelt” GhostDoc to “SubMain” GhostDoc

WeigeltRo — Mon, 06 Jul 2009 21:24:00 GMT

As I wrote in an update to my “The Future of GhostDoc” blog post, the uninstaller of GhostDoc 2.1.3 contains a bug which (under specific circumstances) may lead to losing your Visual Studio settings – I’m really sorry about that.

In the days after the first SubMain release in May (version 2.5.09150) I have helped the guys from SubMain in developing a working uninstaller for old GhostDoc versions, which is now included in the setup of the current GhostDoc version 2.5.09166 (published mid-June, though the website has been only updated recently).

So the “right way” to upgrade from an old “Weigelt” GhostDoc version (up to 2.1.3) to a new “SubMain” GhostDoc version (starting with 2.5.09166) is:

DO NOT uninstall Weigelt GhostDoc
Just run the SubMain GhostDoc setup

Everything else will be taken care of. Future updates (from one version of SubMain GhostDoc to another) also involve just running the installer of the new version.

The Future of GhostDoc

WeigeltRo — Mon, 01 Jun 2009 08:16:00 GMT

Today is the day that I'm finally able to speak about why things have been pretty quiet lately regarding the future of GhostDoc.

I'm happy to announce GhostDoc has been acquired by SubMain, developer of tools like CodeIt.Right. The agreement covers the usage of GhostDoc's documentation generation technology in their products, as well as the availability of GhostDoc as a standalone product. SubMain will continue to maintain and distribute a non-crippled version of GhostDoc free of charge, and will make sure that it will work with future versions of Visual Studio like the upcoming VS2010. The first step is a new version 2.5 of GhostDoc that has been released just moments ago.

For more information please take a look at a Q&A with Serge Baranovsky from SubMain and me that covers past, present and future of GhostDoc.

As I already mentioned in the Q&A, from my experiences of working with the guys at SubMain (both on the legal and the technical stuff), I can say that GhostDoc is in good hands. The developers now have my issue tracking database where I collected and annotated all the feature requests of the recent years, but I also would like to ask every GhostDoc user to please let them know if you have ideas how to improve this tool.

I'd like to use this opportunity to say a big Thank You to all GhostDoc users out their for their (overwhelmingly positive) feedback over the recent years. Thank You!

Update: Important note for existing GhostDoc users
There are uninstall issues with the old GhostDoc version 2.1.3 (and versions before) that under specific circumstances may lead to losing your Visual Studio settings ~~on Vista machines. I'm already working on a solution to the problem (with help from one of the SubMain developers), in the meantime please back up your settings as described in~~ ~~this step-by-step guide~~ before uninstalling the old GhostDoc version. During uninstallation, if a Visual Studio instance pops up and asks you to choose a developer profile, choose one and continue. This will lead to the loss of the settings, which then can be restored by importing the backup you just made before. Note that you have to choose a profile; cancelling the dialog will lead to a corrupted state of the uninstallation.

The new GhostDoc from SubMain is using different install/uninstall/VS integration technology that has been proven in their other products and does not have such problems.

Update 2: Please read this blog post on upgrading to GhostDoc 2.5 and later.

Spanish Configuration File for GhostDoc 2.1.3

WeigeltRo — Fri, 31 Oct 2008 06:40:54 GMT

After an Italian configuration for GhostDoc there's now also a Spanish configuration available. As mentioned for the Italian version, I cannot comment on the quality. Also, please note that GhostDoc is intended for English documentation, which means that tweaking it for other languages is likely to run into problems sooner or later.

On the other hand, a lot can be achieved with the help of some clever custom rules, so I recommend to try out the Spanish configuration. As usual, exporting the current configuration as a backup is definitely not a bad idea.

GhostDoc Tweaks

WeigeltRo — Thu, 28 Aug 2008 20:35:37 GMT

When moving to a new development machine recently, I noticed that I was using a couple of (minor) customizations to GhostDoc on the old machine that are not included in the default configuration. Most of them were rather specific, but three custom rules that may be of general interest are for overrides of the methods ToString(), Equals() and GetHashCode(). Without the rules, the documentation is inherited from System.Object:

/// <summary>
/// Returns a <see cref="T:System.String"/> that represents the current <see cref="T:System.Object"/>.
/// </summary>
/// <returns>
/// A <see cref="T:System.String"/> that represents the current <see cref="T:System.Object"/>.
/// </returns>
public override string ToString()

/// <summary>
/// Determines whether the specified <see cref="T:System.Object"/> is equal to the current <see cref="T:System.Object"/>.
/// </summary>
/// <param name="obj">The <see cref="T:System.Object"/> to compare with the current <see cref="T:System.Object"/>.</param>
/// <returns>
/// true if the specified <see cref="T:System.Object"/> is equal to the current <see cref="T:System.Object"/>; otherwise, false.
/// </returns>
/// <exception cref="T:System.NullReferenceException">The <paramref name="obj"/> parameter is null.</exception>
public override bool Equals( object obj )

/// <summary>
/// Serves as a hash function for a particular type.
/// </summary>
/// <returns>
/// A hash code for the current <see cref="T:System.Object"/>.
/// </returns>
public override int GetHashCode()

The comments are OK at first sight, but I don't really like the references to System.Object, I prefer "the current instance" instead. Fortunately, changing this in GhostDoc is pretty easy.

In general, to replace the generated documentation for a specific method, property, etc., simply define a custom rule and make sure has a higher priority than the rule that would create the documentation otherwise (in the case of the above methods that would be the "inherited documentation" rule).

The new rules are available as a configuration file you can download here (see the included ReadMe for instructions how to use it).

Importing this file will not affect other parts of your configuration, but creating a backup of your current configuration is never a bad idea. After the import the rules will automatically have the highest priority, so no other steps are necessary.

Usage of GhostDoc in Large Corporations

WeigeltRo — Fri, 23 May 2008 14:43:50 GMT

A message to all developers in large corporations out there: If you try/have to approve the usage of GhostDoc because of company policy, you may get the response that legal problems prohibit the usage as no agreement could be reached with the author (i.e. me). To avoid the impression that I'm trying to rip off your company in any way, I'd like to explain this:

If a company approaches me asking whether the usage of GhostDoc is allowed for commercial purposes, I point them to the license which clearly states that this is the case. If company policy still requires an explicit statement regarding commercial use, I don't have any problem with that, either.

But: I will not sign any multi-page legalese for a piece of software that I didn't actively offer, let alone try to sell to a company in the first place. If my freeware license is not compatible with company policy, then that's unfortunate, but it's nothing I will do anything about - sorry.

Italian Configuration File for GhostDoc 2.1.3

WeigeltRo — Thu, 13 Mar 2008 22:29:00 GMT

Even though GhostDoc is intended for English documentation (and there are no plans for future versions to change that), Luca Tagliaferri from Italy has created an Italian configuration file for GhostDoc 2.1.3. While I cannot comment on the quality (I haven't tried it, non parlo l'italiano), I recommend checking it out here. Just be sure to export your current configuration as a backup.

GhostDoc: A Look Back at 2007

WeigeltRo — Sun, 06 Jan 2008 17:58:00 GMT

Here are some statistics for my Visual Studio add-in GhostDoc for the year 2007.

Downloads for Visual Studio 2005

Version 1.9.5 (released back in 2006): 15294
Version 2.0.0 (released 2007–05–01): 11395
Version 2.1.0 (released 2007–06–24): 2351
Version 2.1.1 (released 2007–07–04): 24909
Version 2.1.2 (released 2007–11–25): 4873
Total: 58822

Downloads for Visual Studio 2008

Version 2.0.0 (released 2007–05–01): 444
Version 2.1.0 (released 2007–06–24): 153
Version 2.1.1 (released 2007–07–04): 3202
Version 2.1.2 (released 2007–11–25): 3140
Total: 6939

Downloads for Visual Studio .NET 2003

Version 1.3.0 (released back in 2005): 4409

Donations by chosing an item from my Amazon WishLists (US, UK, DE):

Total: 7 (a huge Thank You to you guys and gals!)

GhostDoc 2.1.2 Released

WeigeltRo — Mon, 26 Nov 2007 00:00:00 GMT

<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>

Quick Facts

Bugfix release
Download on the GhostDoc Website
Users of earlier versions: Please read the ReadMe on upgrading!

About this Release

Version 2.1.2 fixes a problem with side-by-side installations of GhostDoc versions for Visual Studio 2005 and 2008.

What’s New in GhostDoc 2.1.2:

Fixed: GhostDoc versions for Visual Studio 2005 and Visual Studio 2008 interfering when installed side-by-side.
Changed: An upgrade installation by starting the MSI file while an older version is installed is no longer supported, i.e. you have to uninstall GhostDoc before running the new setup. Note that this does not affect an upgrade of the configuration of earlier versions: the configuration file is not removed during uninstallation of the GhostDoc add-in, so you'll still be offered to upgrade your configuration when installing the new version. For detailed installation instructions, please take a look at the ReadMe in the ZIP file.
Added: A few special words for ("of the" trigger and prefix words, "no the" words).

Note that VB.Net support is turned off by default and has to be turned on in the configuration dialog.

Vortrag über Visual Studio Extensibility in Braunschweig

WeigeltRo — Wed, 11 Jul 2007 09:38:00 GMT

Nach Leipzig bin ich nun am nächsten Montag, 16.7.2007, in Braunschweig bei der dortigen .NET Developer Group zu Gast. Ab 19:00 halte ich einen Vortrag über Visual Studio Extensibility mit den folgenden Themen:

Code Snippets
Project/Item Templates und Wizards
Makros
Add-ins

Ein gewisser Schwerpunkt wird bei den Visual Studio Add-ins liegen, wo ich u.a. auf den einen oder anderen Fallstrick hinweisen werde, über den ich bei der Entwicklung von GhostDoc gestolpert bin.

Die Teilnahme ist kostenlos und ohne vorherige Anmeldung möglich, die Veranstalter freuen sich aber bestimmt über einen kurzen vorherigen Kontakt. Veranstaltungsort ist das Restaurant Flair.

Zur offiziellen Ankündigung

GhostDoc 2.1.1 Released

WeigeltRo — Tue, 03 Jul 2007 22:48:00 GMT

<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>

Quick Facts

Bugfix release
Download on the GhostDoc Website
Users of earlier versions: Please read the ReadMe on upgrading!

About this Release

While adding VB.Net support in 2.1.0 I somehow introduced a bug that broke a few things, causing the “Document this” command to not work properly in some situations. In full accordance to Murphy’s Law the bug was hidden in the thin layer between Visual Studio and the main portion of GhostDoc that isn’t covered by unit tests…

What’s New in GhostDoc 2.1.1:

Added: A bit more detailed logging information at certain places. Please take a look at the topic “How to Enable Logging” in the help file for details.
Fixed: "Document this" not working on properties defined in interfaces.
Fixed: Readonly properties in interfaces not recognized properly in VB.Net.

Four Years of Blogging

WeigeltRo — Mon, 02 Jul 2007 20:55:00 GMT

Over the last years I have blogged about various things, but a quick look at the tag cloud of my weblog shows that a large number of posts had one specific topic: My hobby project GhostDoc. It’s easy to forget how long GhostDoc has been in the making (with large pauses in between, of course), so for this “blogiversary” I guessed I’d take a look at the history of GhostDoc in the context of this weblog.

2003–07–02: First Blog post. Just another blogger making his first appearance. Hey, give me some credit, I didn’t use the “Hello World” line…

2003–11–21: First mention of GhostDoc in a blog post. 3:15 am, a good time to post an announcement of a new project.

2003–11–28: Release of GhostDoc 0.5 consisting of a macro, a helper assembly and a looong list of installation instructions. The silence in the blogosphere regarding this release is deafening. Sometimes people see a tool, look past the limited scope of the first release and get excited about what that tool could do in the future. Not in this case.

2004–01–13: Screenshots of GhostDoc 0.9. That version never sees a public release, just a bunch of my colleagues are crazy enough to install it...

2004–06–30: GhostDoc 1.0 is entered as a contest entry to Roy Osherove’s Visual Studio add-in contest. Just minutes before the end of the deadline, in true geek style.

2004–08–13: 1st Place for GhostDoc. One of the prizes: A tour of the Microsoft Campus in Redmond – but I have to get there by myself. Did I mention I live in Germany?

2005–04–15: A GhostDoc Feature I Will Not Implement – this is a classic.

2005–04–21: I receive a copy of the book (Visual Studio Hacks by James Avery) I wrote a chapter for. It may be only one chapter of many, but mum and dad are very proud.

2005–09–07: Microsoft Campus Tour. A slight detour to Redmond on the way to PDC 05. I get there by myself (remember?), I get a tour of the campus. What a cool day.

2005–10–03: GhostDoc 1.3.0. The last version for Visual Studio .NET 2003, and (praise the gods of Extensibility) the last time I have to mess with COM registration of Visual Studio add-ins.

2005–10–04: GhostDoc on Channel 9 – sort of. No interview, just the video that was shown before at the “Show Off” session at PDC 05. Please don’t ask how much time and effort went into these 4:36. It’s ridiculous. And by the way: yes, that’s a German accent.

2005–11–11: GhostDoc is one of "10 Must-Have Add-Ins" in MSDN Magazine –sounds good. Depending on the point of view, the fact that the article was written by James Avery (author of Visual Studio Hacks mentioned above) may have helped, but people seem to agree.

2005–11–15: The results of the Larkware Contest 2005 are in: GhostDoc 1.9.0, the first release for Visual Studio 2005, makes the confusingly named second place (“1st prize” behind a “grand prize”).

2006–04–01: A Sneak Peek at GhostDoc 2.0. Some people obviously didn’t check the date. The “real” 2.0 is released in May 2007.

2006–09–21: GhostDoc Wins the Audience Award at BASTA! Conference. Imagine yourself standing on a stage in full stage light, looking at a pretty huge audience. Imagine ten nominated projects to be voted for by show of hands. Imagine your project getting virtually as many hands as the SharpDevelop project (what? wow!). And then imagine a completely different project receiving the prize, causing overall confusion. That’s what happened on that day. And before things could be cleared up, the tight schedule forced everybody off the stage. Fortunately a review of the notes taken by the beautiful, but slightly numerically challenged hostesses responsible for the counting followed. In the end it turned out that GhostDoc received three votes more than SharpDevelop. Three votes. Funny, that’s two votes by guys of my .NET user group, and one vote by somebody who later told me that he had no idea what GhostDoc was before I gave my elevator speech on stage.

2006–10–20: Whoops... I Just Asked a Question and Now I Won a Prize… Strange stuff happens to me at the Microsoft Visual Studio Extensibility Contest.

2007–01–30: A chapter on GhostDoc in yet another book. Needless to say, mum and dad are proud again.

2007–05–01: GhostDoc 2.0.0 is out. No more thanking my girlfriend in the help file – we married one week after the release of 1.9.5 in August 2006. Version 1.9.6 took much longer than expected and finally became 2.0.0. The huge number of downloads makes me check my hosting package. OK, enough headroom left for many more downloads.

2007–06–24: GhostDoc 2.1.0 is out. VB.Net developers love me again.

2007–07–02: Four years of blogging. Time flies by. Development on GhostDoc will slow down again over the next months as I’ll be working on another hobby project. But I’ll stay in touch with the topic of Visual Studio Extensibility – GhostDoc has turned me into a speaker. Small user group meetings (Paderborn, Leipzig, Braunschweig), the BASTA! conference in September and other appearances are in the pipeline. Things promise to stay interesting.

OK, enough blogging, back to preparing the talk on Friday.

Vortrag über Visual Studio Extensibility in Leipzig

WeigeltRo — Sat, 30 Jun 2007 10:25:00 GMT

Am nächsten Freitag, 6.7.2007, bin ich um 19:30 bei der .NET User Group Leipzig zu Gast und halte dort einen Vortrag über Visual Studio Extensibility.

Die Themen des Vortrags an diesem Abend:

Code Snippets
Project/Item Templates und Wizards
Makros
Add-ins

Ein gewisser Schwerpunkt wird beim Thema Visual Studio Add-ins liegen, wo ich u.a. auf den einen oder anderen Fallstrick hinweisen werde, über den ich bei der Entwicklung von GhostDoc gestolpert bin.

Die Teilnahme ist kostenlos, eine Anmeldung ist erforderlich. Laut dem Organisator Torsten Weber laufen die Anmeldungen gut, noch ist aber Platz für weitere Interessierte.

Anmeldung und weitere Infos hier

GhostDoc 2.1.0 Released

WeigeltRo — Sun, 24 Jun 2007 21:33:00 GMT

<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>

Quick Facts

Support for VB.Net added
Full support for events, including inherited documentation and user-defined custom rules.
Download on the GhostDoc Website
Users of earlier versions: Please read the ReadMe on upgrading!

About this Release

For Visual Basic developers, version 2.1 is what 2.0 should have been: VB.Net support has been added again. Even though I got help (huge thanks to Daniel Root for the translation of the demo project), I spent more time than I wanted on testing, debugging and deployment – in the end it’s a huge number of small things that add up.

C# developers who have to implement many interfaces with events (like I do) will enjoy the full support for events, as it includes a text generation rule for using inherited documentation (VB.Net developers benefit from this of course, too).

What’s New in GhostDoc 2.1.0:

Added: Support for Visual Basic .NET has been added again (was disabled in version 2.0.0), but still is regarded as "experimental". The feature is turned off by default and you have to turn it on in the configuration dialog. Please see the docs for more information.
Added: The setup for the demo project now contains a VB.Net version.
Added: Full rule support for events (configurable default documentation, inherited documentation e.g. for interface implementations, and used-defined custom rules)
Added: New macro $(DeclaringTypeKind) that specifies the kind of type a member is defined in (i.e. class, struct or interface).
Changed: All occurrences of "class" in the default templates have been replaced by $(DeclaringTypeKind).
Changed: As the next version of Visual Studio (codename "Orcas" ) will be named Visual Studio 2008, all texts have been updated accordingly.
Fixed: Documentation of constructors of structs referring to the initialization of a "class" instance.
Fixed: Problems with parameter names starting with an '@' (e.g. "@class").

Visual Studio Add-ins at BASTA!

WeigeltRo — Tue, 05 Jun 2007 00:09:00 GMT

I’ve received an email that I was accepted as a speaker for the BASTA! conference in September in Mainz, Germany . The topic will be the development of add-ins for Visual Studio 2005.

There’s a thing or two that I learned while working on GhostDoc that I’d like to share. My goal is to show both how easy it is to write and debug a simple add-in to be used just by yourself (and maybe your closest buddies), and what it takes to create a “production quality” add-in that runs on the various language versions of Windows and/or Visual Studio.

This will be my first “large” conference as a speaker and I’m sure it will be pretty exciting. Good thing that I’ll have a “warm-up phase” in the next months, speaking about Visual Studio extensibility in general at various .NET user groups (more on that soon).

Note to self: Things to avoid as a speaker

GhostDoc: Support for VB.Net?

WeigeltRo — Mon, 28 May 2007 16:39:00 GMT

Even though GhostDoc is a tool for C# developers, I had (experimental) support for VB.Net in the 1.9.x versions of GhostDoc. When I had to cut down the feature set for version 2.0.0, I cut the features I cared for the least (that’s the freedom of a hobby freeware project). Well, not being a VB.Net developer at all, VB.Net support was one of those.

After the release, more people than expected have asked about VB.Net support for 2.0.0., so even though I’m not a VB.Net developer and I’m not exactly highly motivated to work on VB.Net support, I’ve decided to take a look into this for the next version. No promises on a release date and if I run into larger problems (which I don’t expect, it should all be a matter of working around slight differences in the Visual Studio file code model), I reserve the right to punt the feature to a later version.

What you VB guys could do is to help me by translating the demo project of 2.0.0 to VB.Net syntax and sending it to me. Sounds like only a small thing, but this definitely would save me some time.

Update 2007–06–04: A huge “Thank You” to Daniel Root for the translation of the demo project.