GhostDoc Evaluation Guide

• Introduction
• Generating XML Comments
• Document This
• Re-Document This
• Document Type
• Document File
• Spelling Checker
• Real-time spell checking
• Bulk Spell Checking
• Show Spelling Report
• Previewing Comments
• Building a Help File
• Summary

Introduction

Note: if you would like to get quick four minute overview of the key GhostDoc features before proceeding with the evaluation guide below, you can view this video.

Once you've downloaded and installed GhostDoc Pro, you can access its features in several ways.

First, it is added to the Tools menu in the Visual Studio IDE:

Also, a new toolbar is added to the Visual Studio toolbars:

And, as you'll see as the tutorial progresses, right-clicking inside a code file in the Code window of Visual Studio brings up a context menu of available GhostDoc Pro options.

The three key areas that will be covered in this introductory tutorial are shown below:

1. Documenting your code with XML comments

2. Checking and fixing spelling errors

3. Previewing formatted comments and building a complete Help file

Although GhostDoc Pro offers much more than this, these are the features you'll most often use and are the ones where we believe GhostDoc Pro saves you the most effort.

Documenting Code with XML Comments

Document This

You can create an initial set of XML comments in several ways.

• Left-click on the code item for which you want to create comments.   Then, use the Ctrl+Shift+D hotkey combination to create the comment.
• Left-click on the code item for which you want to create comments.  Then, click on the first button in the GhostDoc Pro toolbar.  Finally, select the Document This menu item. (See screenshot below).

• Right-click on the code item where you want to create comments.  Then, select GhostDoc Pro -> Document This from the context menu that appears.

Whichever way you choose, the XML comment is automatically created. In this simple example, the result will be:

 

As you can see from the summary that's been automatically created in the example above, GhostDoc Pro can analyse the method name and produce an intelligent interpretation of what the method does. It will be most successful if you follow some basic naming rules:

• Follow the Microsoft Naming Guidelines as far as possible (follow this link to view them)
• In particular,
• Use Pascal Casing or Camel Casing for identifier name
• Start method names with a verb wherever possible
• Avoid non-standard abbreviations - ReadXmlFile is OK; ClrMinVals is not.

Re-Document This

This Ghost Doc Pro feature (not available in the free version) lets you instantly update an existing XML comment if you've made a change to the code that will affect the comment.

To implement this feature, left or right click on the code to be commented and then select the Re-Document This menu item. Alternatively, click on the small down arrow on the first button in the GhostDoc Pro toolbar. This will reveal the Document options menu, from which you can select Re-Document This:

In the simple example below, the original method name has been changed from GetPanelMeasurement to GetPanelMeasurements. When the Re-Document This feature is implemented, the summary element of the comment is automatically amended to reflect this change.

 

Document Type

Although best practice is to have only a single class in a code file, there may be times when you have to use code that doesn't follow this practice. In those cases, you can create comments for just one of the classes (GhostDoc Pro only). This is done by using the Document Type feature.

To implement this feature, you select the code to be commented in one of the ways described above, and then select the Document Type menu item.

Document File

If you want to document the whole file in one pass, (only available in GhostDoc Pro), you select the Document File option from any of the three GhostDoc Pro menus described earlier.

Note that not only will this feature add XML comments for each member; it also creates a header for the file:

 

Spelling Checker

Real-time spell checking

GhostDoc Pro includes an intelligent spelling checker. You can enable the Spelling Checker feature either from the Tools -> GhostDoc Pro -> Enable Spell Checking option in Visual Studio, or by clicking the Enable Spell Checking option in the GhostDoc Pro toolbar (3^rd button from the left).

Although using this Toolbar button is the easiest way to turn spell checking on or off, you do also have the option of using the GhostDoc main menu button, or right-clicking in the code pane and using the context menu.

As soon as you activate this feature, real time spell checking will start and the current code page will be checked. Any potential spelling errors will be highlighted with a wavy line underneath the word.

When you hover the cursor over the highlighted word, an options dialog will appear:

As you can see, as well as the standard feature of suggested alternative words, GhostDoc Pro lets you:

• Manually type a replacement word (note that you must first left-click on the word you want to replace)
• Add the highlighted word to the user dictionary. In this case, that word will be accepted in any solution the user opens in Visual Studio in the future.>
• Add the highlighted word to a dictionary for this Solution only.
• Stop spell checking this file and ignore any future errors in the file.
• Stop spell checking any file in the solution that has the same file extension.

Ghost Doc Pro gives you very detailed control over what is spell checked and what is ignored.  To change the default settings, select Tools -> GhostDoc Pro -> Options.

Then, make your choices from the check boxes in the dialog box that appears:

You can choose to include or exclude:

• Regular comments
• String literals
• Symbol names - i.e. Method names, Class members, etc.
• XML comments
• XML content
• XML tags

One particularly smart feature in the GhostDoc Pro Spell Checker is thee way it will split amalgamated words into their individual parts and check each part.

In the following example, the words PartTimer and fullTime are both allowed because GhostDoc Pro has split them into 'Part' and 'Timer', and 'full' and 'Time' respectively, and all four of those words are spelled correctly.

To show how this intelligent analysis works, the following version of the same code snippet will fail the spell check:

As I mentioned previously, if you follow the guidelines for naming, this will greatly help you to create readable, understandable code that can be effectively commented and spell checked by GhostDoc.

Bulk Spell Checking

There are three options for bulk spell checking - Active Document, Current Project, and Entire Solution.

If you want to spell check the active document, the quickest way is to click on the Check Spelling - Active Document button on the GhostDoc Pro toolbar (4^th icon from the right).

All three options can be easily accessed by clicking the down arrow to the right of that button.

They can also be accessed from the Tools -> GhostDoc Pro menu in the Visual Studio IDE.

These menu options are mostly self-explanatory. Whichever of the three options you choose, a Spelling Report will be generated and displayed:

This report displays the individual items picked up by the spell checker, grouped by file name, and listed with their line number in the code file.

When you left-click on any item in this list, the code window will navigate to show you where that selected item is in the code:

You can edit the misspelt word in the code window as shown earlier, and you can also make the change in the Spelling Report. To do this, right-click on the item in the Spelling Report and when the error correction dialog appears, make the change you require. You will have the same list of options that you saw earlier. Any change you make will immediately be reflected in the code and that error will disappear from the list of errors in the Spelling Report.

Show Spelling Report

This option is available from the GhostDoc Pro toolbar or from the Tools -> GhostDoc Pro menu. When you select this option, a Spelling Report based on your most recent option selection will be displayed. That is, if you last selected the Check Spelling - Current Project option, the report will include all relevant files in the project. If your last selection was one of the other two options, the report will include the active document only or every relevant file in the solution, respectively.

Previewing Comments

You can see what an individual XML comment will look like after it's been built as a page in a help file by selecting the Preview Comment feature from the main menu, the context menu or the GhostDoc Pro toolbar (second button from the left - circled in the screenshot below).

This feature is very useful, even with simple comments such as this one:-

This will produce the following output:-

But the Preview Comment feature really comes into its own when you have more detailed or lengthy comments, such as this one:-

The output generated for this example will be:

 

Building a Help File

The Build Help File feature (only available in GhostDoc Pro) gives you several options for building a complete Help file for the solution. This feature is accessed by clicking the small down arrow to the right of the Preview comment button in the GhostDoc Pro Toolbar:

Alternatively, you can access it from the Tools ->GhostDoc Pro menu in the Visual Studio IDE.

When you select it, you're presented with the following dialog:

As you can see from the screenshot above, you have choices for:

• The output path
• Up to four different formats for the compiled help file
• The scope of members that will be included
• The exclusion of projects you don't want to include in the help file

You can also select the Additional Options link and choose to include header and/or footer text in the help pages.

The following screenshot shows an example of a solution compiled as a CHM file:

Summary

This introductory article only covers the features of GhostDoc Pro that you'll likely use most often. There are many more than those covered here.

The core functions that document XML comments and the Ctrl-Shift-D hot keys are what GhostDoc is most famous for. But the additional features of the very smart spell check utility, together with comment preview and Help file building, make GhostDoc Pro a utility that's much more than a plain old comment creator.

I hope that this article will help you see what an invaluable tool GhostDoc Pro can be and that it'll encourage you to download the free trial and try out its features for yourself. We're confident that it will quickly make you more productive and within a very short time of using it, will find GhostDoc Pro to have been one of your better decisions.