Installation

The download includes an installer. Just quit all running instances of Visual Studio, run the installer executable, and hit the install button. This installer simply copies a few files onto your PC (in your My Documents folder). The next time you run Visual Studio, the Addin will auto load and place a new AtomineerUtils menu on the Tools menu.

Note that the installer must be copied onto your computer's hard drive to be run. Due to the executable security features in .net 2.0 it may fail if an attempt is made to run it directly from a LAN folder.

You can link the Addin commands to keypresses as follows:

• In Visual Studio, go to Tools => Options
• Find the Environment\Keyboard section
• In "show commands containing" type "Atomineer"
• The Atomineer commands will be listed. You can now select one, click in the "press shortcut keys" field and press the key combination you wish to execute the command (e.g Ctrl+Shift+D. Suggested keys are given with each command in the documentastion below). When you are happy with the hotkey, click Assign.

Multi-user Installation
If you wish to deploy the AtomineerUtils addin to a number of developers and set them up with common settings (such as including a standard company header in the file header comments), just:

• Install the AtomineerUtils Addin on one PC as detailed above, and set up the options and/or rules as required.
• Copy the Rules.xml and Prefs.xml files from your "My Documents" folder (in Visual Studio 2008\Addins\AtomineerUtils) and place them alongside the AtomineerUtils installer .exe
• Have your developers install AtomineerUtils by running the installer .exe

Disabling or Uninstalling AtomineerUtils
There is currently no uninstaller for AtomineerUtils, mainly because it's trivial to uninstall manually and there are many more important features yet to be implemented.

AtomineerUtils can be temporarily disabled in Visual Studio by choosing the Tools > Add-in Manager menu item, and un-ticking the checkbox to the left of the AtomineerUtils add-in.

To uninstall AtomineerUtils, quit all running instances of Visual Studio. Now open the installation folder (this is usually the 'My Documents' folder - you can run the installer to be reminded of the install location). The install folder contains 'Visual Studio 2005', 'Visual Studio 2008', and 'Visual Studio 10' sub-folders, each of which contains an 'Addins' folder. Delete the 'AtomineerUtils.Addin' file from each of these Addins folders. You may then delete the Visual Studio 2008\Addins\AtomineerUtils folder to remove all program files and your rules and preferences.

Command Reference

1. Add Doc Comment for a code element
2. Document all in this scope
3. Create C# or C++/CLI Property or a C++ Accessor from a member variable declaration
4. Implement/Declare C++ method
5. Open C++ Source or Header
6. Hide DocComments using Outlining
7. Hide Attributes using Outlining
8. Copy As Text
9. Word Wrap comment
10. Preferences controlling the behaviour of the Atomineer commands

Command: Add Doc Comment

This command creates or updates a Doxygen or DocXml-compatible description comment block for C#, C++/CLI, C++, C, or Visual Basic code.

Usage
Place the cursor in an appropriate line:

• Anywhere in the first line of the file (for a file header)
• Anywhere in the first line of a "code element" (namespace, struct, enum, class, function, property or variable definition) or in any blank lines or documentation comments immediately preceeding the element
• Anywhere within a normal (non-doc comment) //-style comment block (to simply reformat the text with word wrapping)

...and execute the command.

Description
When you execute the command, the code around the cursor will be interpreted and an appropriate header comment will be inserted just above the current code element. As much useful information as possible will be extracted from your code, and where possible default comments will be inserted to save you unnecessary typing.

A number of helpful pieces of information are added to save you typing obvious comments, e.g:

• If a method/property overrides a base class method/property that has a DocComment, or a method is an overload for which another overload already has a DocComment, this command will duplicate the pre-existing DocComment to save you re-typing as many details as possible.
• Author and current date are inserted
• All parameters, generic type parameters, thrown exceptions and a return value are entered into the comment as required, with appropriate formatting inserted to make everything line up tidily.
• Special methods (constructors/destructors/operators, event handlers, indexers, etc) have a brief description automatically filled in.
• Methods with common names or prefixes (e.g. GetHashCode or methods with names like GetXXX, CalcXXX) will be given some default documentation
• Various parameter types will have part or all of the description text filled in as a basis for the most likely text you'll need.
• Common return types (e.g. bool for success/failure) cause default return value descriptions to be included.
• The cursor is positioned in the <summary> section, ready for you to describe your code.

Example function documentation headers, completely auto-generated.

(Note that if you don't like the default style/layout of the comments, they are easily configurable (see some examples) in the AtomineerUtils Pro Options and also in Rules.xml. Note that the free version (AtomineerUtils) does not support this customisation option).

	////////////////////////////////////////////////////////////////////////////////////////////////////
	/// <summary> Event handler. Called by the TaskListCtrl for KeyDown events. </summary>
	///
	/// <remarks> Jason Williams, 12/04/2009. </remarks>
	///
	/// <param name='sender'>  Source of the event. </param>
	/// <param name='e'>       Event information. </param>
	////////////////////////////////////////////////////////////////////////////////////////////////////

	void TaskListCtrl_KeyDown(object sender, KeyEventArgs e)
	{
	}

	////////////////////////////////////////////////////////////////////////////////////////////////////
	/// <summary> Initialises the file buffer. </summary>
	///
	/// <remarks> Jason Williams, 12/04/2009. </remarks>
	///
	/// <exception cref="NotImplementedException"> Thrown when the requested operation is
	///                                            unimplemented. </exception>
	///
	/// <param name="fname">      Filename of the file. </param>
	/// <param name="buffSize">   Size of the buffer. </param>
	/// <param name="resetCache"> true to reset cache. </param>
	////////////////////////////////////////////////////////////////////////////////////////////////////

	public void InitFileBuff(string fname, int buffSize, bool resetCache)
	{
		throw new NotImplementedException();
	}

	////////////////////////////////////////////////////////////////////////////////////////////////////
	/// <summary> Gets or sets the foreground colour. </summary>
	///
	/// <value> The colour of the foreground. </value>
	////////////////////////////////////////////////////////////////////////////////////////////////////

	public Color FgColour { get {}; set {} }

For more examples see: DocXML format comments and Doxygen format comments.

Note that these use the default style for the comments, but the style is very configurable (in AtomineerUtils Pro). See below for details.

If a documentation comment already exists, it will be parsed and updated - for example if you add a new parameter to a function, or change a Property by adding a get/set method, the existing comment will be updated to reflect the new details. This feature will also serve to automatically convert most existing DocXml/Doxygen comments into the AtomineerUtils format, or to tidy doc comments after you have hand-edited them.

If enabled, the word-wrap option will automatically reformat each comment entry to keep it tidy. The indentation level of the first line of each entry will be used in all subsequent lines. The word wrap will preserve blank lines, any lines at a greater indent level than the first line of the entry, and lines starting with certain text (examples (e.g., c.f., i.e.), bullet lists (starting with -, *, +), etc). In blocks of entries (e.g. <param> lists), the text within entries will all be lined up into a single column to enhance readability.

In AtomineerUtils Pro, word wrap is suppressed for blocks of text that lie between <pre>, <code>, @code...@endcode, and @verbatim...@endverbatim tags. Note that these start/end tags must be the first nonblank text on the line.

If enabled, the number of blank lines above and below the doc comment will be corrected to a user-specified standard to help keep code files tidy. The default is to enforce a single blank line above and below the comment.

Any DocComment entries that are no longer required (e.g. deleted or renamed parameters) will be inserted at the end of the comment block in this form:

///### <param name='value'>  This parameter has just been deleted</param>

This preserves any text from these entries in case you wish to re-use it anywhere else (e.g. a renamed parameter). If you invoke the command a second time, any such 'deleted' lines will be automatically removed to save you having to manually clean up the comment.

Tips:

• If the cursor is in a normal comment (a block of lines commented-out with single-line comments - //), the comment will be automatically reformatted using the word wrapping system, allowing you to easily update the text in your comments and leave AtomineerUtils to keep everything tidy.
• If you wish to document exceptions that pass through your method from a called method (i.e. uncaught exceptions), document them as 'Passed when' rather than 'Thrown when" and the comment will be preserved.
• By default, DocXml format will be generated, but adding a \file: doxygen comment at the top of the file (or forcing Doxygen format in the Options) will switch documentation automatically into Doxygen format.
• Note that some documentation addins use the Intellisense system within Visual Studio to get information on the code element, so they fail if your code is not in a compilable state (which I find is much of the time as I document as I write the code, not afterwards). AtomineerUtils only uses Intellisense to augment its own built in parser, so it is able to correctly handle code even if it is currently not in a compiled/compilable state. This means it also works for any sufficiently C/C++/C#-like language (e.g. Java, and Maya 3D .mel script).

Changing the comment layout style (AtomineerUtils Pro only)

The style of the comment blocks is quite configurable. High-level settings can be changed using the Atomineer Utils Options (available from the Atomineer.Utils menu in Visual Studio), while lower level improvements to the automatic documentation can be made by editing the Atomineer Auto-Documentation Rules XML file. See the Preferences and Doc Comment Rules sections below for details.

Command: Document all in this scope

This command searches a namespace, class, interface, struct, or enum scope and applies the Add Doc Comment command to each major code element within it.

Usage
Place the cursor in the declaration (i.e. somewhere in the line with the 'namespace', 'class' etc) of any of the above code element types and execute the command.

Description
When you execute the command, the code within the next scope (from the '{' following the cursor position) will be scanned for child code elements to document. The Add Doc Comment command will be executed on each, adding or updating the comment in the usual way. Each will generate a new undo step.

This can be used in the following ways:

• Quickly and easily build the documentation structure for all the entries in an enum definition,
• Convert existing comments (e.g. in the Visual Studio default XmlDoc /// format) into the configured AtomineerUtils format,
• Quickly update existing documentation after changing the AtomineerUtils block format or preferences,
• Automate an initial documentation pass.

After executing this command it is highly recommended that you read through and update the resulting documentation to be sure that it is complete, correct and accurate.

Command: Create C# or C++/CLI Property, Create C++ Access Methods

C++: Creates simple inlined "Get" and "Set" methods to access a member variable, making it much quicker and easier to make members private and properly encapsulate your class data.

C++/CLI: Creates a Property for your member variable, implementing default get/set methods.

C# (VS2005): Creates a Property for your member variable, implementing default get/set methods, and adding handy debugger attributes.

C# (VS2008/2010): Augments the VS2005 behaviour with a two-stage conversion. It will convert a member variable into an auto-property, and convert an auto-property into an explicitly implemented property with a backing field.

Usage
In your C++ header or C# class, place the cursor anywhere in the middle of a member variable or auto-property declaration, then invoke the appropriate command.

Description
A preference option (see below) is available that specifies the style of the member variables that are consumed and created by this command. However, a variable need not match the template to be processed correctly - it may have a lower-case first character, or an underscore as a prefix/suffix (e.g. 'variable', '_variable', 'Variable_', 'mVariable' or 'm_Variable').

C++: Get and Set methods will be created, and inserted into the document above the preceeding "public/protected/private:" tag. For known simple types (int, float, etc) the accessors will pass by value. For unknown types, it assumes complex types (struct/class) and will pass by const-reference. (Pro only:) The names used for the getter/setter can be configured in the preferences.

C++/CLI: A property is defined, and inserted into the document above the preceeding "public/protected/private:" tag.

C# 2005: A property is defined, and is inserted immediately above the member variable declaration. The protection level for the variable will be changed to private, and the Property will use the protection level previously assigned to the variable (or public if it was private).

It also adds attributes to improve debugging of the property (stops the debugger single-stepping into the property get/set function, and hides the member variable in the Locals window so that you don't end up with the property and the member variable both being displayed alongside each other). (A using System.Diagnostics; will be automatically added as well if required)

C# 2008/2010: When executed on a member variable, it is converted into an auto-property. When executed on an auto-property, it is converted into an explicitly implemented property with a backing field. The backing field will use the variable naming style configured in the preferences.

You can convert from a member variable to an explicit implementation by just executing the command twice in succession.

A preference is provided to allow you to set a template for the backing field naming style. For an auto-property called 'MyProp', the default (a blank prefix) is to generate a backing field 'myProp'. With a template specified, other styles (e.g. '_MyProp', 'm_MyProp' 'mMyProp', '_Member_MyProp_' can be generated.

Note that debugger attributes are not added in VS2008/2010, as these IDEs provide much better debugger stepping facilities, so the attributes are no longer necessary.

public:
private:
  int      mInteger;
  MyClass  mComplexClass;

public:
  int GetInteger(void) const                         { return(mInteger);             };
  void SetInteger(int Integer)                       { mInteger = Integer;           };

  const MyClass &GetComplexClass(void) const         { return(mComplexClass);        };
  void SetComplexClass(const MyClass &ComplexClass)  { mComplexClass = ComplexClass; };

private:
  int      mInteger;
  MyClass  mComplexClass;

public:
  property int Integer
  {
    int get()           { return(mInteger); }
    void set(int value) { mInteger = value; }
  }

  property const MyClass& ComplexClass
  {
    const MyClass& get()           { return(mComplexClass); }
    void set(const MyClass& value) { mComplexClass = value; }
  }

private:
  int      mInteger;
  MyClass  mComplexClass;

public int Integer
{
   [DebuggerStepThrough] get { return(mInteger); }
   [DebuggerStepThrough] set { mInteger = value; }
}

[DebuggerBrowsable(DebuggerBrowsableState.Never)]
private int mInteger;

// Original variable
private int mSpeed;

// After one execution, an auto-property
public int Speed { get; set; }

// After the second execution, an explicit property with backing field
public int Speed
{
    get { return(mSpeed); }
    set { mSpeed = value; }
}
private int mSpeed;

Command: Implement/Declare C++ method

(C++ only)
This command allows you to:

• Create a skeleton implementation of a method from its header declaration.
• Add a header declaration for an existing implementation.

Usage
Place the cursor into the first line of a function declaration/implementation and invoke the command.

Description
When executed in a header (.h) file:
This converts the declaration for a method in the header, and any contiguous block of single-line comments preceeding it, into a skeleton implementation and a full documentation comment, which are appended to the source (.cpp) file.

• All default parameters and modifiers like "static" are stripped from the implementation
• Any block of C++ single-line comments immediately above the function are concatenated into a single line and moved into the description field in the header
• A skeleton function body is appended, and in the case of simple types, a simple default return value is provided.
• A documentstion comment is atuomatically generated, and the text cursor is left in the summary section.

When executed in a source (.cpp) file:
This adds a declaration for the method in the header (.h) file. Where possible, AtomineerUtils will locate the correct namespace/class to add the declaration into. The new declaration is inserted at the bottom of the class.

For this command to work, the .cpp and .h file must have a common filename, and both be part of your Visual Studio Project.

Header declaration:

// Creates a new Thingummy containing the required number of Wotsits
Thingummy *CreateThingummy(CreateInfo *pInfo, int NumWotsits = 12) const;

Resulting source file implementation (with doxygen-style comment)

////////////////////////////////////////////////////////////////////////////////////////////////////
/// \fn	Thingummy *MyClass::CreateThingummy(CreateInfo *pInfo, int NumWotsits)
///			
/// \author	Jason Williams
/// \date	6/6/2005
///
/// \brief	Creates a new Thingummy containing the required number of Wotsits
///
/// \param	pInfo		If non-NULL, the information
/// \param	NumWotsits	The number of wotsits
///
/// \retval	NULL if it fails, else
///
////////////////////////////////////////////////////////////////////////////////////////////////////

Thingummy *MyNamespace::MyClass::CreateThingummy(CreateInfo *pInfo, int NumWotsits) const
{

  return(NULL);
}

Command: Open C/C++ Source or Header

When executed in a C/C++ source/header file, opens the matching header/source file.

Usage
Execute the command when you are working in a C/C++ header or source file.

Description
When executed in a C/C++ source/header file, this simply opens the matching header/source file. The files must be in the same project, and use the same base filename.

Command: Hide DocComments using Outlining

Uses Visual Studio's Outlining feature to hide all DocXml Comments in your code.

Usage
Execute the command at any time, or have it automatically executed whenever you open a code document by enabling the preference.

Description
This command hides all multi-line DocComments (lines beginning with ///) in your file using the Outlining feature of the Visual Studio Editor. This allows you to see 'just the code' without the comments interfering with your view. To see the text of the comments, just hover the mouse over the [...] to show a tool-tip. To edit a comment, double-click the [...] to re-display the outlined text.

Command: Hide Attributes using Outlining

Uses Visual Studio's Outlining feature to hide Attributes in your C# code.

Usage
Execute the command at any time, or have it automatically executed whenever you open a code document by enabling the preference.

Description
This command hides all C# Attributes in your file using the Outlining feature of the Visual Studio Editor. This allows you to see 'just the code' without the attributes interfering with your view. To see the text of the attributes, just hover the mouse over the [...] to show a tool-tip. To edit the attribute, double-click the [...] to re-display the outlined text.

Command: Copy As Text

Copies selected text onto the clipboard in a simple, clean format for use in other programs.

Usage
Just as with a regular copy: Select the text you wish to copy and execute the command. If no text is selected, the entire line containing the cursor will be copied.

Description
When you copy text from Visual Studio to other applications, it includes colour codes for the syntax colouring scheme. This is not very useful when you want to put the text into a document that will be printed or emailed, especially if you use a non-white background colour! Additionally, Visual Studio copies the text verbatim - including surplus indentation that pushes your text to the right when pasted, and Tab characters that can cause the formatting to become a complete mess.

This command addresses all of these issues by copying the selected text in your document to the clipboad as plain text. It (optionally) strips unnecessary indentation from the block, and (optionally) converts tabs into spaces.

Note that for the formatting to appear correct in the pasted text, you must display it using a monospaced font (e.g. Courier New).

Command: Word wrap comment

Word-wraps the text in a comment block.

Usage
Place the cursor anywhere inside a // comment block (that spans one or more lines). Invoke this command. (Note that the Add Doc Comment command also does this, to save having to use another keypress, but this command is included so that it can be used in isolation and (e.g. from macros) if preferred)

Description
The text in the current //-style comment block will be word-wrapped according to the preferences in the DocComment section of the AtomineerUtils options.

Preferences

The AtomineerUtils => Options... command will show a preferences window. This allows you to choose from a number of options to tweak the commands to operate as you want them to:

Doc Comment - General settings tab

• Documentation style: Doxygen, DocXml, or auto-discovered (any file with a @file: or \file: doxygen comment at the top will use Doxygen comments; otherwise DocXml format will be used)
• Doxygen command prefix: Sets whether doxygen tags use the \ or @ prefix. Ignored in DocXml comments.
• User Name: Normally, author comments will use the user's login name, but you can enter a custom name here to override it
• Date format. This is a DateTime formatting string that controls how dates are displayed in doc comments. e.g. 'd', 'dd-mm-yyyy', 'dddd, d MMMM YYYY' etc
• Date culture. Use the current culture, or set a specific culture to have your dates formatted in the language/style of your preference.

In addition, these Doxygen-specific options can be set:

• Doxygen tags can be of the form '\brief' or '@brief'
• Add single-line comments to right of code element. By default, AtomineerUtils will add a single-line comment on the line above any variable that you document. Check this option to tell AtomineerUtils to instead add the comment to the end of the same line (note that this is only fully compatible with Doxygen, as DocXml comments must always precede the code element that they document)
• Suppress 'brief' tag. Doxygen supports the JAVADOC_AUTOBRIEF style where the brief description entry does not have a tag introducing it. AtomineerUtils Pro supports this style of Doxygen comments.
• Add declarations/prototypes to Doxygen comments. With this enabled, the declaration of the code element being commented will be added to the doc comment (i.e. @class, @fn, @property, etc)

Doc Comment - Border Style tab

This section controls the border of the doc comment (AtomineerUtils Pro only). There are two standard comment styles that Visual Studio will recognise (it will syntax colour them and extract them as documentation comments for intellisense). Doxygen also recognises and parses these formats, so they are the recommended base style:

• 'Triple slash' format. In this form, every line in the doc comment is prefixed by ///
• 'C-style' format. In this form, a C-style /** ... */ comment is used, with a double asterisk at the start to indicate that the comment contains XML documentation.

AtomineerUtils Pro supports these formats (and more) by allowing you to define the format of optional first and last lines (the top and bottom 'separator' lines) and an optional prefix that is used on every line in the body of the comment. These can be almost anything you want, as long as they meet these primary requirements:

• The content of the documentation block needs to be excluded from compilation, so you need a well-formed //, /*...*/ or #if...#endif block as a minimum.
• The pair of separator lines, or the line prefix, must be distnct from other text in your file so that AtomineerUtils can correctly locate, parse, and update existing comments.

Any of these can be set to (none) to remove them from your comment style entirely. The default format is the 'triple slash' format with ////////// separator lines to demark the comment block, but several other common and demonstration formats are provided in the combo boxes, or you can type in a custom string.

Note that the top separator can now be a multi-line block (using \n in the text to denote newlines). If you use this, you must use a /** ... */ comment style for AtomineerUtils to be able to correctly parse and update existing comments. Within this top separator, you can also optionally use %type% to embed the type of the code element (Class, Method, Property, Constructor, etc) and %name% to embed the code element's name in this separator section. A three-line demo format is available to trial this form.

Lastly, AtomineerUtils can optionally enforce a specific number of blank lines above and/or below each DocComment to ensure a consistent style throughout your code with a minimum of effort.

Doc Comment - Entry Style tab

• The first combo box controls how single and multiple-line entries are formatted into the comment. A picture explains these options best - see these examples. As you change these options, a preview is shown at the bottom of the window so you can see the effect.
• The second combo box applies the same rules to groups of similar entries (such as parameter lists).
• Add whitespace between entry tags and text. By default, AtomineerUtils tries to make comments easy to read by adding whitespace at the start and ends of entries. When unchecked, AtomineerUtils will strip off any whitespace at the ends of the tag.
• Start each entry with a Tab character (rather than a space). By default, AtomineerUtils is set up to make it easy to write comments. After the opening tag of a comment, it inserts a tab character so that when you press return to add a new line, you can quickly tab to the start column to write a block of text easily. However, if you prefer, a space can be used. This reduces the whitespace in the comments, at the cost of having to type more characters to line up subsequent text tidily.
• Start all entries in a block at the same text column. If you have a 'block' of similar entries (e.g. a param list) AtomineerUtils will normally indent the entry text for all the items to line up at the same column. This significantly improves readability, but can result in a lot of wasted space. Disable this option to just format each entry in isolation.
• (AtomineerUtils Pro only) Add blank lines between entries. You can control where blank lines are inserted between entries in your comments in the templates in Rules.xml. However if you simply wish to eradicate all blank lines, this option overrides the template to stop them being inserted.
• Word wrap can be enabled or disabled. Additionally, you can set the column at which wrap occurs, and whether that column is absolute (from left edge of page) or relative (from the left hand side of the comment block)

Live Preview pane

This section (at the bottom of the three Doc Comment tabs) shows an example comment, illustrating the sort of style you can expect from the settings you have chosen. It updates live as you change the preferences. Note that this is a guide only, but it will give you a fairly reasonable idea of how the real comments will appear.

Source Outlining tab
Documentation comments can be collapsed/hidden using Visual Studio's Outlining feature. These options control how and when outlining occurs:

• Choose to automatically apply outlining for all files as they are opened
• Hide the entire comment, or leave the first line visible
• Remove or retain the whitespace between the comment and the code element

A similar set of options are available when outlining Attributes

• Choose to automatically apply outlining for all files as they are opened
• Remove or retain the whitespace between the atribute and the code element

Misc tab
This contains the preferences for several of the simpler commands, as well as general AtomineerUtils preferences.

'Menu Items' allows you to hide menu items for AtomineerUtils commands that you don't use. Why clutter the VS menus with options you never use? This just helps to keep the user interface clean and useful.

'Copy as Plain Text command' allows you to control the format of the text that Copy As Text will place on the clipboard.

Doc Comment Rules

The DocComment output of AtomineerUtils is extremely configurable via a simple Xml file. Locate the file in your "My Documents" folder (or the install location you chose in the AtomineerUtils installer) under:

My Documents\Visual Studio 2008\Addins\AtomineerUtils\Rules.xml

The rules are very simple yet powerful. Usage of the rules is heavily documented within this Xml file to allow you to augment the rules for yourself.

The rules fall into three main groups:

• Templates. Each template defines the comment block layout to use for a given type of code element, allowing you to specify exactly what information is expected in the comments for (e.g.) methods, properties and classes.
• AutoDoc rules. These describe how to generate auto documentation for different code element types (classes, structs, enums, exceptions, methods, properties, return codes, parameters, etc). You can easily augment the default logic to add new automatic documentation based on the names and types relating to each code element, to allow AtomineerUtils to recognise and support the naming conventions you use.
• Abbreviation expansions. This section allows AtomineerUtils to expand abbreviations to full English terms (e.g. "src" -> "source") to produce more readable auto-doc commenting.

If you augment the rules, please consider emailing me your updated rules file for possible inclusion into following releases.