What does GhostDoc do?
GhostDoc installs a new command - "Document This" into Visual Studio code editor context menu. When editing a source file, you simply navigate cursor into the language element you want to document (or in front of it, in the same text line), and call the "Document This" command by either pressing the hotkey you assigned to the command GhostDoc setup or using the context menu. GhostDoc analyses insert an XML documentation comment, much like typing "///" in front of a language element, but with a major difference: for specific language elements like methods and properties, GhostDoc attempts to generate large parts of the actual documentation (for other language elements like e.g. enums and their values, an empty summary will be generated).
If a class member is an interface implementation or override of a base class member, GhostDoc will use the existing documentation, regardless of where the interface or base class comes from. So basically what this means that you can re-use tons of documentation that Microsoft wrote - just remember the last time you've implemented IEnumerable and thought about how to comment the GetEnumerator() method.
In the cases where no existing documentation can be used, GhostDoc attempts to analyze the code element name. Under certain conditions (we'll get to that later) GhostDoc actually does very good job. Often enough the results are not accurate or even plain silly, but on average correcting the mistakes/problems in the generated documentation takes less time than writing the whole comment from scratch.
But how can a tool with virtually no understanding of the English language generate often pretty accurate documentation? Well, the basic idea is pretty simple: GhostDoc assumes that your code follows Microsoft's Design Guidelines for Class Library Developers:
- you are using
PascalCasing or camelCasing to write identifier names consisting of multiple words - your method names usually start with a verb
- you do not use abbreviations in identifier names
If you follow these rules, for example, use ClearCache() instead of Clrcch(), and choose more or less self-documenting identifier names, there's a good chance for GhostDoc to split the identifier names into words, tweak and/or shuffle the words a little and produce a comment that, while not being perfect, gives you a head start on the way to a good documentation.
As already mentioned, GhostDoc does not really understand English identifier names, nevertheless it attempts to apply certain rules to increase the quality of the generated comments:
- Handling of verbs (GhostDoc assumes the first word of a method name is a verb):
Add -> Adds, Do -> Does, Specify –> Specifies - "Of the" reordering (using trigger words like
width, height, name, etc.): ColumnWidth -> Width of the column - Combined with special handling of specific prefix words:
MaximumColumnWidth -> "Maximum width of the column" instead of "Width of the maximum column" - Automatic detection of acronyms consisting of consonants (
Html -> HTML), combined with a list-based approach for other acronyms (Gui –> GUI) - Use of a list of words where that should not be headed by a "the" (
AddItem -> Adds the item, but BuildFromScratch -> Builds from scratch)
Here's example of what GhostDoc is able to do: If you a method DetermineInputCacheSize, GhostDoc will create the summary "Determines the size of the input cache." If you want to see more examples, take a look at the demo project.
Since the quality of the comment depends on the identifier name and its structure, using GhostDoc for a longer period of time actually teaches writing consistent and self-documenting identifier names, which is definitely a nice added bonus.
What doesn't GhostDoc do?
GhostDoc cannot do miracles, and the way it generates documentation may not work well with your personal style. If you are not following the Microsoft Guidelines, you will most likely run into problems.
When GhostDoc is able to re-use documentation from interfaces and base class members, it simply copies the comments over. It does not check whether the comment still applies, which, for example, becomes obvious when you document an override of the ToString method of System.Object. The generated summary is "Returns a System.String that represents the current System.Object." (<see> tags omitted for clarity), where it should read "Returns a System.String that represents the current MyNamespace.MyClass.". A developer quickly figures out that in this case, System.Object has to be replaced, but a tool like GhostDoc cannot (at least not without an extensive code analysis).
Intentionally, GhostDoc is not a tool for creating the complete documentation for a given source file in one go. You can only document one member at a time, because you always have to check and extent the results of each auto-generated comment to make it clear and actually useful.
What is GhostDoc Pro?
GhostDoc Pro is an enhanced version of the product that gives you complete control over your XML Comment content and layout as well as automates XML Comment generation via batch actions.
The Pro version has all features of GhostDoc and adds:
- T4 based XML Comment templates - total control over your XML documentation content and style
- Document Type - generates XML comments for entire type/class
- Document File - generates XML comments for entire file
- Source code Spell Checking
- XML Comment Preview
- Generate XML Comment based Help Documentation
- StyleCop compliant comments
- Exception Documentation