Contents tagged with GhostDoc
-
Microsoft Campus Tour
Today was the day: the day of the Microsoft Campus tour which was a prize for winning Roy Osherove’s Visual Studio add-in last year (read here).
from left to right: my colleague Jochen Manns, Keen Brown (MS),
me, my other colleague Sascha LehmannI’d like to thank Keen (who filled in for Josh) and Sara – it was a fun day!
The things that amazed me the most: the size of the campus and the speed at which Sara talks ;-)
-
GhostDoc - The Movie ;-)
I just submitted my video for the PDC 05 “Show Off” session. Producing this video was much more work than I expected, which means that I won’t be able to release the final of 1.3.0 before the PDC (I’m already leaving on Thursday, as I’ll take a little detour on my way to L.A).
The hardest part of the video was speaking English and presenting GhostDoc – either I mis-pronounced a word or stumbled over a wicked combination of “s” and “th” (which I wouldn’t care about in a real-life situation), or I made a mistake during the presentation. Fortunately with some editing, many things can be fixed.
If the video is accepted, it will be shown at the “Show off” session and will be made available after the PDC. Sorry, I can’t post a download link before the PDC.Update: The video was accepted and shown at the PDC, and is now up on Channel 9.
-
GhostDoc 1.3.0 Beta 2 Released
Beta 2 of GhostDoc 1.3.0 has been released, which in terms of features should be pretty close to the release version. The documentation has made a major step forward, but stills needs some work (proofreading, more and better Howtos, especially tutorials for defining custom rules).
What’s new in 1.3.0 beta 2 compared to beta 1:
- Added: New options for determining what should be the representation of the C# language keywords "true", "false" and "null" in a documentation comment.
- Added: New Macros $(True), $(False) and $(Null) to be used in text templates.
- Added: New Macros for the current date, the name of the current user, etc. ("environment macros").
- Added: New custom text that will be added once to a newly added documentation comment. As this text will not be updated, can be used for e.g. marking the date and time when a class member was added.
- Added: New summary template for default property rule (text generation was hard-coded in previous versions).
- Added: Template for methods with parameters for SingleWordMethodRule (text generation was hard-coded in previous versions).
- Added: Preliminary documentation for the dialogs.
- Changed: Default textual representation of "null", "true" and "false" back to the values of version 1.2.1 (<c>null</c>, <c>true</c> and <c>false</c>)
- Changed: Value text of the default property rule is no longer empty by default.
- Changed: Macros: Words.AsSentence -> Words.AllAsSentence
- Fixed: Various bugs related to customization features.
For those who missed the release of beta 1 and still work with 1.2.1:
1.3.0 Beta 1 compared to 1.2.1:
- Added: New rules for using "inherited" documentation, including base class members and members of implemented interfaces. The inherited documentation will be cleaned from single <para> tags and the texts will be tweaked (e.g. when the summary for an interface method starts with "When implemented by a class....", and the summary is inherited by the method that is an implementation).
- Added: GhostDoc updates existing documentation. Empty tags (<summary>, <returns>, <param>) will be filled according to the generation rules, existing text remains unchanged. The update reorders the parameter documentation if the order of the parameter changes, and removes documentation for parameters that no longer exist.
- Added: User defined ("custom") rules using e.g. regular expressions for matching names and/or types.
- Added: New rule for "On..." methods -- no more "Ons the click" ;-)
- Added: Rule for static constructors.
- Added: Rule for the Finalize method (destructor syntax in C#).
- Added: Rule for event handler methods as they are created by the WinForms designer.
- Added: Rule for boolean properties.
- Added: Rules (both custom and built-in) can now be customized by editing templates that are used by the text generation rules.
- Added: Export of partial configurations is now possible (e.g. for exporting only a single custom rule).
- Changed: Summary text of the default constructor rule is now 'Initializes a new instance of the <see cref="ClassName" /> class.', i.e. uses the wording in the Microsoft documentation. The old "Creates a new <see cref="ClassName" /> instance" is debatable - is it the constructor that actually creates the instance, or is the constructor called when the instance is created? Thus the Microsoft wording is preferrable.
- Changed: The configuration is now stored in the ApplicationData\Weigelt\GhostDoc directory. Old configurations in the installation directory (versions before 1.3.0) will be upgraded and stored in the new location.
- Fixed: <returns> tag no longer disappears if the return type is an array.
- Fixed: Overall handling of array types.
FAQ
- When is the final coming out?
Before the PDC. - What about VS2005 support?
After the PDC.
-
GhostDoc 1.3.0 Beta 1 Released
I’m pleased to announce that beta 1 of GhostDoc 1.3.0 has been released. A big “Thank You” to the steadily growing number of testers who helped me testing a couple of preview builds, pointed out a few minor issues and gave me an overall “Thumbs up”.
What’s New
- New: New rules for using "inherited" documentation, including base class members and members of implemented interfaces. The inherited documentation will be cleaned from single <para> tags and the texts will be tweaked (e.g. when the summar for an interface method starts with "When implemented by a class....", and the summary is inherited by the method that is an implementation).
- New: GhostDoc updates existing documentation. Empty tags (<summary>, <returns>, <param>) will be filled according to the generation rules, existing text remains unchanged. The update reorders the parameter documentation if the order of the parameter changes, and removes documentation for parameters that no longer exist.
- New: User defined ("custom") rules using e.g. regular expressions for matching names and/or types.
- New: New rule for "On..." methods -- no more "Ons the click" ;-)
- New: Rule for static constructors.
- New: Rule for the Finalize method (descructor syntax in C#).
- New: Rule for event handler methods as they are created by the WinForms designer.
- New: Rule for boolean properties.
- New: Rules (both custom and built-in) can now be customized by editing templates that are used by the text generation rules.
- New: Export of partial configurations is now possible (e.g. for exporting only a single custom rule).
What’s Missing
There are a couple of small features I’d like to see in 1.3.0 final. And then there’s a huge update of the help file waiting to be done.
FAQ
- When is the final coming out?
My personal deadline is end of August. - What about VS2005 support?
I guess i’ll wait for the PDC bits of VS2005
-
GhostDoc: Looking for Testers
I’m planning a first public beta of GhostDoc 1.3.0 towards the end of July. A couple of private builds have already been released to colleagues and people on the net who offered their help. So far feedback has been pretty good. People like the new features, some issues have been found, most of them could be fixed in the following builds.
Now I would like to have a couple more people to test the current build. If you’re interested, contact me via the contact form. Please tell me about your system (e.g. which other Add-ins are installed), since when you have been using GhostDoc and how often you use it. I’ll then send you an email with the download link (when waiting for a reply, please take time zone differences into account ;-).
Here are the new features you can try out in the preview:
- New rules for using "inherited" documentation, including base class members and members of implemented interfaces. The inherited documentation will be cleaned from single <para> tags and the texts will be tweaked (e.g. when the summary for an interface method starts with "When implemented by a class....", and the summary is inherited by the method that is actually the implementation).
- GhostDoc now updates existing documentation. Empty tags (<summary>, <returns>, <param>) will be filled according to the generation rules, existing text remains unchanged. The update reorders the parameter documentation if the order of the parameter changes, and removes documentation for parameters that no longer exist.
- User defined ("custom") rules using e.g. regular expressions for matching names and/or types.
- New rule for "On..." methods -- no more "Ons the click" ;-)
- Rule for static constructors.
- Rule for the Finalize method (destructor syntax in C#).
- Rule for event handler methods as they are created by the WinForms designer.
- Rule for boolean properties.
- Rules (both custom and built-in) can now be customized by editing templates that are used by the text generation rules.
A few words about the quality of this preview: Answering the obvious question “does it fry my data and/or my Visual Studio installation?”, I can say that the Visual Studio integration and installation/uninstallation are at least as good as in version 1.2.1, so I wouldn’t hesitate to run the setup on production machines. The current problems are mostly missing features, some usability issues and the online help that hasn’t been updated yet.
-
"Visual Studio Hacks" Book: Excerpts Online
Excerpts from the “Visual Studio Hacks” book by James Avery have been published on the OnDotNet web site.
- Master the Command Window
- Create Comments Faster (this one is about GhostDoc and was written by me)
- Run Unit Tests Inside of Visual Studio
- Hack the Project and Solution Files
- Refactor Your Code
Unfortunately I didn’t have much time to read the book in the previous weeks. Yesterday was the first day of the year that the local “Freibad” (public outdoor swimming pool) was open, so I took it with me to read it while sunbathing. And I must say that “Visual Studio Hacks” passed my personal “Freibad test”, i.e. it was interesting enough to be read in a noisy environment, with interruptions (kids playing soccer in the sunbathing area), and without a computer nearby. Other books that passed this test in previous years are “C# Unleashed” by Joseph Mayo, “Code Complete 2” by Steve McConnell and the “Extreme Programming Pocket Guide” by chromatic.
Back to “Visual Studio Hacks”: I consider myself an advanced user of Visual Studio, so many of the hacks are not really new to me, but most of those hacks contained some bit of information I didn’t know yet or completely forgot about. What I really liked about the book is that it’s not a simple collection of tips that the author barely tried himself. You notice that in the little details like the solutions to problems you may not encounter immediately, but will run into sooner or later in your daily work (e.g. the infamous “Call rejected by callee” error). So far I’ve read the first half of the book and I couldn’t find anything that I would consider of little value – I wish could say that about many other computer books.
-
GhostDoc News
Development of GhostDoc is moving slowly, but steadily towards version 1.3.0, which will be the first release since October (wow, incredible how time flies by). So what has happened since the last GhostDoc News on this blog back in January? Looking from the outside, not much. If you remember the screenshot published back then, “all I did” was add the rule configuration tree to the configuration dialog and make all the buttons work:
Editing the settings of a rule looks something like this:
Behind the scenes, things have been far more complicated and time-consuming than expected. But the good news is that editing/exporting/importing the configuration (of rules and everything else) is pretty much finished.
So what’s the big deal about moving some configuration data around? I won’t go too much into detail, but simply imagine two computers A and B runnning GhostDoc (e.g. at home and at work) and you change some settings of a rule on A, change the priority of another (or maybe the same) rule on B. Then add some rules on A, remove some rules on B, and of course all these changes happened days after the last time you synced both computers. There are many opportunities to fry the user’s configuration data and while a fully automatic synchronization simply wasn’t possible, even just asking the user what to do (and then frying his/her data — nah, just kidding) already took a huge effort.
So what are the next steps? I’ll now write new text generation rules to solve some of the most often reported issues (e.g. “On…” methods) and the user defined rules mentioned in the January post. That will be pretty much the feature set for 1.3.0. Other ideas I have been playing around with will have to wait until 1.4.0 or later.
Visual Studio Beta 2
As people have been asking: Yes, I’ll look into releasing a version of 1.3.0 for Visual Studio 2005 Beta 2. There will not be a port of 1.2.1, though.
Other News
- I saw that GhostDoc is mentioned on the Microsoft Visual C# Developer Center — nice.
- There’s a new section on the GhostDoc home page, the “GhostDoc Hall of Shame” showing some of the more obscure results of the text generation. If you have weird/funny/sad/unexpected results, don’t hesitate to drop me a line.
-
My Copy of "Visual Studio Hacks" Has Arrived
I’ve received my free copy of Visual Studio Hacks by James Avery which I got for contributing hack #69 “Create comments faster” (page 280 – 285). These pages contain an introduction to – you may have guessed it – GhostDoc. After reading my part (of course ;-) I took a quick look at the rest of the book and I must say the first impression is really good. Obviously, after reading only a few pages, it’s too early for me to give a final verdict, so I’ll leave that for a later blog post.
A nice surprise for me is that my original text wasn’t edited that much (I wasn’t really sure what to expect, as English isn’t my primary language).
-
A GhostDoc Feature I Will Not Implement
I’ve received a number of requests for a new GhostDoc feature for documenting a whole source file at once. This feature is filed as item #45 in my issue tracking system, and its status is “rejected”.
The texts generated by GhostDoc are suggestions generated by some stupid code that breaks identifiers into separate words and juggles them around. Each and every text generated by GhostDoc has to be checked by the developer, and should be revised by the developer if necessary. Depending on your coding style, the time required for checking and revising the generated text usually is less than writing everything from scratch, i.e. using GhostDoc saves you time.
So that’s the idea: GhostDoc guesses some documentation text, you check the results, and in the end you’ve saved some time.
I’m pretty sure that many of us know at least one “motivationally challenged” developer who is very likely to skip the part where you actually have to use your own brain. If such a person has to document a class member by member, there’s at least a little chance that he/she will notice texts that are just too stupid (e.g. such classics like “Toes the string.” and “Ons the click”). But can you imagine the same person given the feature of running GhostDoc on a whole source file at once? DailyWTF, anyone?
-
GhostDoc in Upcoming Book "Visual Studio Hacks" by James Avery
Ok, now that the book “Visual Studio Hacks” by James Avery has been announced officially, I’m finally allowed to talk about my (small) contribution to the book: My Visual Studio add-in GhostDoc is one of the “hacks”.
Shortly after GhostDoc won Roy Osherove’s Add-In contest in August 2004, James contacted me to write a quick run-down on using GhostDoc. He couldn’t offer any money (if you wonder why, you should read this), but hey – a few hours work for a free book isn’t too bad ;-)
Let’s see what the editors at O’Reilly thought of my English writing skills (or lack thereof?) and what’s left of my original text…
