at*mineer
Follow us on Twitter
productsreviewscompareskinsuserguidefaqdownloadchangeslogin

Product Comparisons

Below is a comparison of a group of similar Documentation Comment generation tools. These are the most recently available releases of the tools that we are aware of (updated every couple of months). We have tried to be totally objective, so if anything is missing or incorrect in this table, please let us know and we'll double-check our facts.

The systems compared below are:

  • VS: the built-in Visual Studio features
  • ND: .NET Documentor (1.0)
  • CM: CommentMaker (1.9.8)
  • GD: GhostDoc (4.5),
  • GDP: GhostDoc Pro (4.5),
  • APD: Atomineer Pro Documentation (7.67),

Note that some popular commercial add-ins advertise that they include code-documentation support features. However, these add-ins are not specialised for documentation, and generally offer only very primitive support in this area (typically insertion of fixed 'boilerplate' comment blocks). As such, they are not directly comparable to the documentation-specific add-ins listed here.

Supported Languages (in Visual Studio 2005, 2008, 2010, and 2012)VSNDCMGDGDPAPD
Visual Basicyesyes-yesyesyes
C#yesyes-yesyesyes
C++/CLI-yesyes--yes
C++--yes--yes
C-----yes
Java-----yes
UnrealScript-----yes
Configurable comment generation for any other filetype-----yes

Supported Documentation FormatsVSNDCMGDGDPAPD
Documentation XMLyesyes-yesyesyes
Doxygen--yes--yes
JavaDoc-----yes
Qt-----yes
Legacy documentation conversion-----yes

Documentation Block FeaturesVSNDCMGDGDPAPD
Generate new Doc Comment blockyesyesyesyesyesyes
Create comments for all code elements in a type in one pass-yesyes-yesyes
Create comments for all code elements in a file in one pass-yesyes-yesyes
Create comments for all code elements in a project in one pass-yesyes---
Support single-line comment format, e.g. /// ...yesyesyesyesyesyes
Support multi-line comment format, e.g. /** ... */--yes--yes
Optionally place a #region around the doc comment-----yes
Optionally place a #region around the entire code element-----yes
Optional, configurable top/bottom separator lines--yes--yes
Configurable whitespace within the comment block--yes--yes
Configurable whitespace above/below the comment block-----yes
Configurable ordering of block elementsyes-yes-yesyes
Configurable and custom documentation tags/commands--yes--yes
Optionally use end of line ///< comments for variables & enum entries-----yes
Optionally only document public/protected/internal-----yes
Independent configuration settings per-Solution or per-Project-----yes

Documentation Entry FeaturesVSNDCMGDGDPAPD
Word-wrap entry text-----yes
File header comments--yes--yes
File footer comments-----yes
Namespace comments-----yes
Member variable summary-----yes
Class summary-----yes
Generic Class type-parameters---yesyesyes
Interface summary-----yes
Enum summary-----yes
Enum entry summary-----yes
Struct summary-----yes
Union summary-----yes
Typedef summary-----yes
#define summary-----yes
Method (Sub/Function) summary---yesyesyes
Method parameters---yesyesyes
Method [in,out] parameters--yes--yes
Method [optional] parameters-----yes
Generic Method type-parameters---yesyesyes
Template type-parameters-----yes
Method exceptions thrown---+ (entries are added, but no description is supplied)+ (entries are added, but no description is supplied)yes
Method returns---+ (a few)+ (a few)yes
Property summary---yesyesyes
Property value-----yes
Indexer summary---yesyesyes
Indexer value-----yes
Events & Event Handlers---yesyesyes
Delegates-----yes
Operator overloads---yesyesyes
Extension methods-----yes
Code element declaration support (Doxygen)--yes--yes
Class/Interface <seealse cref='base-class'/> entries-yes---yes
Overridden method/property <seealso cref='base-method'/> entries-yes---yes

Deriving documentation from existing documentationVSNDCMGDGDPAPD
Copy base class method documentation to derived class override-yes-yesyesyes
Copy interface method documentation to derived class implementation-yes-yesyesyes
Copy best-match method documentation to sibling overloaded methods-----yes
Copy best-match parameter documentation to parameters in other methods-----yes
Copy best-match property documentation to parameters-----yes
Copy best-match member variable documentation to parameters-----yes

Auto-generation enginesVSNDCMGDGDPAPD
Documentation-generation rules000~203~2032274
Abbreviation expansions00000555
'of the' reordering---yesyesyes
a/an/the correction-----yes
Heuristic and Dictionary-based acronym handling---yesyesyes
Configurable word replacement dictionary-----yes
Pluralisation---yesyesyes
Punctuation correction-----yes
Configurable prefix (e.g. 'm_member', 'lpszString', 'IInterface', 'CClass') cleanup-----yes

Documentation Block UpdatingVSNDCMGDGDPAPD
Easy update (allow cursor to be in lines/comments above the code element to update)-----yes
Update comments for all code elements in a type/file in one pass-yes--yesyes
Update comments for all code elements in a project in one pass-yes----
Update declaration entries to match edited method signature (Doxygen)-----yes
Update 'typeparam' and 'param' entries to match edited method signature---yesyesyes
Update 'returns' entries to match edited method signature-----yes
Update 'exception' entries to match exceptions thrown in method-----yes
Update property description (gets, sets, gets or sets) to match implementation-----yes
Update indexer description (get, set, get or set) to match implementation-----yes
Word-wrap user-edited documentation entries-----yes
Optionally convert <, >, & into legal XML/HTML entities-----yes
Enforce whitespace rules-----yes
Enforce user-defined entry ordering-----yes
Configurable removal of 'illegal' block elements-----yes
Support for custom entry types-----yes

Documentation Block ConversionsVSNDCMGDGDPAPD
Convert regular // comments into documentation comments-----yes
Convert end of line ///< or //!< comments into documentation comments-----yes
Convert between different block styles and layouts-----yes
Convert between DocXML, Doxygen, Javadoc and Qt formats-----yes
User-editable (VB) macros to allow conversion of legacy comment blocks-----yes

Documentation/Comment Block Live Editing HelpersVSNDCMGDGDPAPD
Create a new doc-comment as /// (C#) or ''' (VB) is typedyes----yes
Create a new doc-comment as /// (C++/CLI, C++, C, Java, Unrealscript) is typed-----yes
Leave the cursor in a useful place when a doc comment is createdyes----yes
Continue comment block with correct indentation when newlines are typed-----yes
Join comment lines together (stripping prefixes) when deleting newlines-----yes
Automatically extend bullet-lists when newlines are typed in comments-----yes
Automatically reformat pasted text to integrate it into comments-----yes
Spelling checker----yes-

Special featuresVSNDCMGDGDPAPD
Even works on code that doesn't compile-----yes
Rich-text documentation viewer----yesyes
CHM documentation export----yes-


Generated documentation comparison

Quite a number of add-ins are available that build some form of documentation blocks automatically. However, almost every one of these add-ins provides only the most basic features - typically they provide empty comments, sometimes populated with fixed text for a few specific code elements (such as constructors). Only GhostDoc and Atomineer (to our knowledge) are capable of documenting a wide range of code elements in a context-sensitive manner.

Some typical comments from these two add-ins are shown below, to give a rough idea of the quality of documentation they produce. 

public class VehicleDetailsDlg : Form { ... }
 GhostDocAtomineer
summary - (no documentation generated) Dialog for setting the vehicle details. 

public float CalcSalesTax(List<float> priceList)
 GhostDocAtomineer
summary Calcs the sales tax. Calculates the sales tax.
priceList The price list. List of prices.
returns - The calculated sales tax. 

int NumUsers { get; }
 GhostDocAtomineer
summary Gets the num users. Gets the number of users.
value - The total number of users. 

int Min(int value1, int value2, int value3)
 GhostDocAtomineer
summary: Mins the specified value1. Determines the minimum of the given parameters.
value1 The value1. The first value.
value2 The value2. The second value.
value3 The value3. The third value. 

public static bool Contains(this string[] textList, string textToFind)
{
	if (textList.Length == 0)
		throw new InvalidOperationException("textList cannot be empty");
}
 GhostDocAtomineer
summary Determines whether [contains] [the specified text list]. A string extension method that determines if this collection contains a given object.
Invalid operation exception - Thrown when the requested operation is invalid.
textList The text list. The textList to act on.
textToFind The text to find. The text to find.
returns <c>true</c> if [contains] [the specified text list]; otherwise, <c>false</c> true if the object is in this collection, false if not.

 
Copyright © 1996-2013 Atomineer. All Rights Reserved. Any trademarks reproduced in this text are the property of their respective owners. Contact us