Contents tagged with GhostDoc
-
Crunch Mode
I'm busy putting the final touches on GhostDoc for entering it here:
Testing, cutting features, testing, writing release notes, testing, fixing last minute bugs, testing, ...
Hmm. Some parts of developing software a more fun than others... ;-)
-
GhostDoc Progress
After a pretty long break from working on GhostDoc I'm now back on track. My goal is to have a release ready for entering Roy's add-in contest and now that the deadline has been moved to June 30, I'm pretty sure I can make that happen.
-
GhostDoc Delay
As the public interest regarding GhostDoc was next to zero (which isn't necessarily a bad thing at this phase of the project), I've done a quiet release of version 0.9, available only to some of my colleagues at work. The overall reaction was very positive and a lot of "cool, I want more" ideas poured in which showed that they did "get" what GhostDoc is about. Unfortunately, when planning the future direction for GhostDoc, it became pretty obvious that the way the rules for method and properties are currently defined is a dead-end.
So I have decided that there will be no public release of version 0.9. I will completely rework GhostDoc towards a more extensible architecture, even if this means I have to throw away a lot of work done in January. No idea how long this will take, but I try to make several small steps to minize the risk of getting carried away. More details will follow later.
-
GhostDoc has reached Dogfood Status
A lot has happened since my last GhostDoc related posting. The addin version of GhostDoc is pretty close to a first public release. I'm already using it both at home and at work, but it's a bit complicated to keep the two configurations in sync. It's not really rewarding to define more specialized rules if you can't move them to a different machine. So I've decided to delay the release until some very basic import / export functions are implemented. They will be ugly, but straightforward to use and fully sufficient for a 0.9 version.
Here are two screenshots of configuration dialogs:
1. The main dialog
2. The dialog for editing a property rule:
-
GhostDoc News
My project GhostDoc is now a VS.Net Addin. But before I release the next version, there are a couple of things on my ToDo list I want to finish first:
- A rewrite of the configuration storage code
- A GUI for editing the configuration
The actual documentation generation will be the same for the next release; there are already a lot of things that can be done with the existing features, just by using the capabilities of the configuration settings.
More information on what's planned for GhostDoc after the release (no specific date yet).
-
Introducing: GhostDoc
[2004-08-22] As this old post has a pretty high Google rating, I'd like to emphasise that it does not contain up-to-date information. If you are interested in GhostDoc, I'd suggest to take a look at the GhostDoc homepage./// <summary>
/// GhostDoc is a VS.Net macro for automatically generating those
/// parts of a C# doc comment that can be deduced from the name
/// and/or type of a method or property.
/// </summary>In my previous post I already mentioned my current project "GhostDoc"; now a first public release is ready. Before I start explaining a lot of things, why don't just watch the small video showing GhostDoc in action (400k).
Now here's the basic idea for GhostDoc: When writing documentation comments (e.g. for an API) I tend to use "documentation patterns", e.g. the infamous "Gets or sets a value indicating whether" for a boolean property. And my summary often consists of what I call "method/property name as a sentence plus X", with X being something that adds some value. Example: if I have e.g. a method "void CreateDocumentBuffer(int bytes)", I write "Creates the document buffer with the specified size in bytes". Of this sentence, typing the words "Creates the document buffer" is pretty brainless labor (because I already typed the method name). So wouldn't it be cool if some macro would do that for me? Well, that's what GhostDoc is about; or to be exact, what the very first version started with.
GhostDoc works the following way: When you hit a hotkey inside the c# source editor of VS.Net, GhostDoc finds out what kind of code element the cursor is currently in (e.g. a method), determines the name and (return) type and uses these to look up a matching template for the documentation comment (the templates are stored in an XML configuration file).
The current version of GhostDoc is definitely a "technical preview". It's the result of a macro that grew bigger and bigger until it had to be supported by code in a C# assembly. Now all code is in the assembly and the macro consists only of a single method call. So GhostDoc is not (yet) a VS.Net addin. It's pretty stable; stable enough for me to use it both at home and at work. The good thing is that because of the way GhostDoc works, it simply can't mess up your source code (unless VS.Net has some serious problems) and undo works nicely, too.
Installation
The installation is currently completely manual
- Download GhostDoc_0.5.zip
- Unzip it to a directory of your choice
- Move "Weigelt.Tools.GhostDoc.dll" and "Weigelt.Tools.GhostDoc.Texts.xml" to the "Common7\IDE\PublicAssemblies" subdirectory inside your VS.Net 2003 installation directory.
- Start Visual Studio and go to the Macros IDE (Tools - Macros - Macros IDE)
- Open the MyMacros node in the project explorer
- Add a reference to the "GhostDoc macro support" assembly (it will appear automatically in the list of the "Add Reference" dialog)
- Right click "MyMacros" and "Add existing item", browsing for the "GhostDoc.vb" file in the directory you unzipped to.
- Save and leave the Macros IDE.
- Open the options dialog (Tools - Options) and define the keyboard bindings; simply type "ghost" in the "show commands containing" input field and you'll see the two commands (I use Ctrl-D for CreateComment, and Ctrl-Shift-D for RefreshConfiguration, but it's completely up to you)
Getting started
Move the cursor into a method or a property without a documentation comment, and hit e.g. Ctrl-D (if a documentation comment already exists, nothing will happen). Note that your code should use .NET naming conventions, otherwise the results can be pretty strange, sometimes even funny. GhostDoc is highly configurable, but in this version the default configuration is far from being finished. Simply take a look into the file "Weigelt.Tools.GhostDoc.Texts.xml" and you'll get an idea how things work.
Known Issues
- As already mentioned, the generated summary can sometimes be pretty off. In many cases, a new rule in the configuration will help - if you add such a rule, please send me a copy.
- There is virtually no user documentation. Some information can be found inside comments in the configuration file.
Plans for the future
- More entries in the configuration file
- A GUI for editing the configuration
- Better installation
- A release including source code, maybe opening a GDN workspace.
- ...
Update 01.12.2003: I'm now working on turning GhostDoc into a Visual Studio .NET addin. So if you're put off by the ugly installation of the current version, you may want wait just a little.
-
Coming soon... GhostDoc
It's pretty late here in Germany, but I cannot go to bed without posting screenshots of the first successful runs of my new VS.Net macro (with a little help from some C# code):
Before:
After:
(Macro called three times)
GhostDoc helps writing API documentation by generating the "obvious" parts of the documentation from the identifier names. This is not a replacement for real documentation, but it's a good starting point. The text generation can be customized, here's an excerpt from the configuration file:
<Properties>
<!-- Default -->
<Property>
<summary>
$$NameAsSentence$$
</summary>
</Property>
<!-- Default for all boolean properties -->
<Property type="System.Boolean">
<summary>
$$Access$$ a value indicating whether [$$NameAsWords$$]
</summary>
</Property>
<!-- Specific definition for the "Enabled" property -->
<Property type="System.Boolean" name="Enabled">
<summary>
$$Access$$ a value indicating whether this $$Class$$ instance is enabled
</summary>
</Property>
</Properties>I'll have a beta ready soon - stay tuned.
