Contents tagged with GhostDoc
-
GhostDoc News
As mentioned on the GhostDoc homepage (which I use for the smaller status reports that also contain more private stuff), I’m back working on version 1.3.0. Since Christmas I have managed to spend a good amount of time on GhostDoc, but things are not progressing as fast as I had hoped. There are a couple of tough problems to solve that come with one of the major goals for 1.3.0: User-defined rules.
In addition to user-customizable rules as mentioned in a previous post, it will be possible to define new rules by specifying regular expressions for matching e.g. method signatures, and templates containing macros for generating documentation texts. This may not be as flexible as writing new rules in C# code (which will have to wait until the framework has been stabilized), but there’s a lot that can be done with this simple solution.
Things like upgrading from earlier versions (without losing customizations) and synchronizing configuration files between installations e.g. at home and at work turn out to be pretty tricky even though these topics already have been addressed in previous versions. Right now I’m busy refactoring and extending the code for reading/writing/importing/upgrading/merging configuration files, and hey — my existing unit tests actually caught a couple of nasty bugs and thus saved me a lot of time!
To finish this post, here’s a screenshot showing the rule configuration tree (no new rules shown here, though):
I’m far away from any release, which in turn is a chance for your suggestions and feature requests to be included in 1.3.0. Simply drop me a line in an email (ghostdoc at roland-weigelt.de).
-
The Power of First Impression
After months of ZIPping up the GhostDoc source files every now and then, I finally have a source code management solution running (better late than never ;-). I've built and set up a server from spare parts, mainly to be used for storing files (e.g. backups and VMWare images), on which I installed SourceGear Vault. Using SourceSafe at work, this was an obvious choice for me. Usually I don't shy away from learning new things, but this time I didn't want to invest time to learn to use a system with a different philosophy (like e.g. SubVersion).
Now I have to admit a few things: While there are quite a few things I'm really good at, I have no or only superficial knowledge when it comes to administering/configuring
- databases
- IIS
- ASP.net applications
So this is me, not wanting to invest a lot of time, and I want to install a product that
- uses a database (MSDE in my case, which I have never installed before)
- is running on IIS
- is an ASP.net application
And you know what? I got things running without any problems worth mentioning. The combination of a good installer (e.g. no editing of configuration files required) and an installation guide on the product's website with lots of screenshots enabled me to install this product. Creating a repository was also pretty easy and just a matter of minutes.
So I'm happy to report that GhostDoc is now under source control.
Maybe it turns out that I just installed the worst product imaginable. Maybe things go wrong from now on in every imaginable way. But right now I trust this product. It just feels right. From the splash screen (nice, but not too fancy) up to the help file (not really spectacular, but it was able to answer the few questions I had). Everything made good first impression.
Now there's another application I installed on the server (I will not mention the name here, as it would be pretty unfair). When I start it, I get a "SqlException: SQL Server does not exist or access denied" error message. I couldn't find what to do in the documentation, the product's website does not have a FAQ, there's no forum, only a email address I can write to. This is what I'll to, because I'm pretty sure that once things are running, the application will be what I was looking for. But I guess you agree that the first impression is spoiled.
As a developer I know that I'm completely unfair here, but as a customer (even though in both cases I don't have to pay as a single user) I don't care about being fair. Whether you like it or not, the first impression plays a vital role how users view your software.
So do yourself a favor: When you release software (even if it's just a small tool), invest enough time in what could be called "the most important minutes" of your program. After a couple of months since the release of GhostDoc, I'm happy to notice people praise the "out of the box experience". Let me tell you it didn't come easy. Things weren't perfect from a start and a lot of time and testing went into getting things right. I actually bought VMWare Workstation especially for testing GhostDoc on different system configurations (virtual machines simply rock, period). Did all the effort pay of? After all, I could have implemented lots and lots of features, so GhostDoc would produce less funny results in certain situations and would be as useful as I know it could be. But all I can say is yes, it was worth the effort. GhostDoc was downloaded a bit more than 1000 times (all versions combined) and while this may not be too impressive, I'm proud that I didn't receive a single question about the first steps. I receive bugs and feature requests regarding the text generation, people wanting to tweak things, people wanting to code their own rules, but not a single of those "I can't get it to run, what now?" questions that quickly eat away lots of time from actually developing software.
-
GhostDoc News
While work on GhostDoc has slowed down a bit, I still haven't lost my enthusiasm for this project. It has proven to be useful for me in my daily work and feedback from users has been really positive so far. Most of the feature requests I receive are already on my TODO list, which I regard as a good thing as it shows that I'm on the right track with my plans. And it helps me to prioritize the items on the list -- so don't hesitate to drop me an email with your suggestion.
Plans for 1.3.0
The most wanted feature is proper handling of "On..." methods.... Oh yeah, this will be the next rule to be implemented and I plan to include it in 1.3.0. Interestingly, every person who wrote me about the funny mess the current version of GhostDoc is producing of e.g. "OnClosing" had a different idea of what the generated text should look like. Which leads to another problem: The more text GhostDoc actually adds to a simple processing of identifier names, the more people wish to change these additional texts to their liking (quite understandably).
That's why version 1.3.0 will allow users to customize generated texts by editing template texts containing macros for dynamic content. The macros are similar to those for the pre-build and post-build steps in the Visual Studio IDE. For example, the template text for the summary of a constructor is "
Creates a new $(DeclaringTypeName.ShortNameAsSee) instance". As in Visual Studio, you don't have to type out the macro name, but can select it from a list (or, to be more exact, from a tree).Here's what selecting a macro for e.g. the summary of a property will look like this (more or less, the screen shot is from a dialog in a GUI test, not the actual addin):
As usual I won't talk about a release date; when I feel comfortable releasing 1.3.0, I'll release it ;-)
-
GhostDoc 1.2.1 released
While working on version 1.3.0, I ran across some minor issues in 1.2.0 that were pretty easy to fix. These fixes are now available in version 1.2.1.
Download: on the GhostDoc homepage
What's New:
- Fixed: Under certain circumstances, acronyms used in parameter names that are referenced in summary texts are not handled correctly (the first character of the acronym is shown in lowercase).
- Added: Better visual feedback after pressing "Import" and "Upgrade" buttons during setup, now the wait cursor appears while the determining the differences between the two configuration (current/imported or default/imported).
-
GhostDoc 1.2.0 released
Version 1.2.0 originally was planned to contain mostly new rules; but it turned out that many of the planned rules require some kind of individual customization/configuration, so this had to be taken care of first. Internally, this release now does use configuration settings for each rule (e.g. templates for the generated texts), but the dialogs for actually editing these settings have not been implemented yet (they will be part of a 1.3.0 release). From a user's point of view, version 1.2.0 contains some important bug fixes and new rules for handling properties and methods with names starting on "Is", "Has" and "Can".
Download: on the GhostDoc homepage
Note for users of version 1.1.2
During setup, GhostDoc upgrades configuration settings of previous version (stored in the file "Weigelt.GhostDoc.gdc"). Usually this file is located in the GhostDoc installation directory, but due to a bug in version 1.1.2 the file was stored in the root directory of one of your hard drives.
If you have made changes when using version 1.1.2 that you want to keep, you can import the old settings using the "import" feature on the configuration dialog (see the help file for more information), then delete the ".gdc" file in the root directory.
What's New:
- Added: New rules for handling method names starting with "Is", "Has" or "Can".
- Added: New rule for handling property names starting with "Is" or "Has".
- Added: Internal changes in preparation for rules to be configurable individually (affecting e.g. import/export) in future versions.
- Changed: During the setup phase, importing and upgrading configurations can now be distinguished(button and window title renamed).
- Fixed: Editing the adjectives for the "of the" reordering does not enable the "Apply" button; pressing the "OK" button does not store the changes. If anything else is modified in the configuration dialog, the changes will be stored correctly.
- Fixed: Configuration file is stored at the wrong location (root of the installation drive). This bug was introduced in 1.1.2.
- Fixed: GhostDoc can be affected by installing other add-ins, sometimes setup dialogs are shown again when Visual Studio is started.
-
GhostDoc 1.1.0 released
A new version of GhostDoc, the winner of Roy Osherove's Visual Studio add-in contest, is available - finally! Some bugfixes, some new features, an all-new help file, some eye-candy... but the most important work was done on turning a contest entry (with some corners cut to meet the deadline) into a stable foundation for the coming versions. To have this whole thing manageable, I pretty early on decided to push most of my ideas and the feature requests of users to version 1.2.0 -- looking back, a wise decision as finishing 1.1.0 turned out to be pretty painful.
Download: on the GhostDoc homepage (Edit 2004-08-31: removed link to a specific version)
First Steps
- Install the MSI
- Start Visual Studio to complete the setup
After installation, the Windows start menu contains a sub-menu "Programs -> Weigelt -> GhostDoc" with shortcuts to the help file and the demo project.
If you hate reading manuals, you should at least take a look at "How do I see some action without reading boring stuff?" -- the link to that topic is on the start page of the help file ;-)
What's New:
- Added: Configuration dialog for acronyms and words involved in reordering operations happening when sentences are generated from identifier names (e.g. "of the", "no the" words).
- Added: Import/Export of settings (on the configuration dialog).
- Added: Help file and help in dialogs.
- Changed: The "of the" reordering now checks for certain adjectives affecting "of the" trigger words and takes them into account while reordering.
Example: If "size" is configured as an "of the" trigger word and "initial" as an adjective, then "initialPageBufferSize" will be translated to "initial size of the page buffer" instead of "size of the initial page buffer" (as in Version 1.0x). In contrast, "primaryPageBufferSize" will still be translated to "size of the primary page buffer" (because "primary" is not on the list). - Changed: The rule for method names consisting of only one word now checks for parameters and adjusts the generated doc comment accordingly ("<Verb> this instance." for methods without parameters, "<Verb> the specified <first param text>." of methods with parameters.).
- Fixed: Bug in the automatic detection of acronyms -- words consisting of consonants and only one vowel at the start of the word (e.g. "Add") were classified as acronyms.
- Fixed: Bug in the handling of all-uppercase words in identifiers -- the words (e.g. ID) were split into single characters.
- Fixed: Bug when documenting properties in interfaces -- XML documentation comment didn't appear (reason was a fat bug in Visual Studio's CodeDOM; I'll have to check whether this still exists in VS2005 as soon as I get the copy I ordered at Microsoft).
-
Feels like Christmas...
...and these are just some of the prizes I've won:
The software prizes were distributed via internet and thus are kinda hard to show (and a CD-R isn't that spectacular to look at), but are really cool. And another book is still on its way -- winning stuff is fun!
-
1st Place for GhostDoc !!!
Wow... what a way to start into the weekend... GhostDoc was voted the #1 Addin in Roy's Addin Contest! If you haven't tried it yet, why not download it and give it a whirl. There's even a "how do I see some action without reading boring stuff" demo included. After installing the MSI, simply open the program menu -> Weigelt -> GhostDoc and read the quickstart document for the few steps necessary.
Right now I'm busy preparing 1.10; I don't know when it will be ready for release (working on a CHM help file can chew up enormous amounts of time), but it shouldn't be that far away. The feature set is frozen and I'll touch the code only if a serious bug is found in 1.02. Note that funny results of the text generation don't count as a bug ;-)
I have a huge list of improvements waiting for 1.20 and later (e.g. generation rules for virtual "On..." methods), but first I want a clean release of 1.10.
-
Add-in Contest Website Live, GhostDoc Now Available
The contest results are not finalized yet, but the official website went live [via Roy]. All add-ins entered in the competition can now be downloaded, GhostDoc is available here.
Edit 2004-08-14: I've disabled the download link that was pointing to version 1.01; the most recent version can be downloaded from the GhostDoc website.
-
GhostDoc is RTM (or is that RTRAC?)
(RTRAC = Released to Roy's Addin Contest ;-)
23:49 the mail with my contest entry GhostDoc left my outbox.
I'm exhausted. Several nights of only 4 hours sleep are taking their toll. Mostly addin related problems, stuff not working that worked perfectly for weeks. COM registration issues, you name it.
I had to cut features, there are things that could have been better, but that sucker is out the door.
I feel satisfied.