at*mineer
Follow us on Twitter
productsreviewscompareskinsuserguidefaqdownloadchangeslogin

Atomineer Pro Documentation User Guide

1. Installation 
2.1 Add Doc CommentAdd a documentation comment for a code element.
2.2 Document all in this ScopeAdd/Update documentation comments for many code elements in a single pass.
2.3 Document all in this FileAdd/Update documentation comments for many code elements in a single pass.
2.4 Document all in this ProjectAdd/Update documentation comments for an entire Project in one pass.
2.5 Document all in this SolutionAdd/Update documentation comments for an entire Solution in one pass.
2.6 Document all in Chosen FilesAdd/Update documentation comments for a selection in one pass, with additional options.
2.7 Delete Documentation in this FileDelete all documentation comments form a file.
2.8 Comment editing enhancementsLive editing helpers for improved editing of normal comments and documentaiton comments.
2.9 Documentation ViewerView window that shows documentation for code elements as you browse your source.
3.1 Align code into columnsIn blocks of repetitive text, line up columns for enhanced clarity and readability.
4.1 Create C# or C++/CLI Property or a C++ AccessorConvert a member variable declaration into a Property or Accessor implementation.
4.2 Implement/Declare C++ methodGiven a header file declaration, create a skeleton implementation; given an implementation, add its declaration to the header file.
4.3 Open C++ Source or HeaderSwitch quickly between related source and header files.
5.1 Hide DocComments using OutliningUse the Visual Studio Outlining facility to hide Documentation comments.
5.2 Hide Attributes using OutliningUse the Visual Studio Outlining facility to hide Attributes.
5.3 Copy As TextCopy code to the clipboard without any syntax colouring or unnecessary indentation.
5.4 Other Menu ItemsAtomineer Options, About and Check for Updates.
5.5 Suppressing and Allowing UI promptingCommands to allow use of Atomineer from within Macros or Extensions.
6.1 PreferencesControlling the behaviour of the Atomineer commands.
6.2 Doc Comment Rules and TemplatesControlling the layout of doc comments, and the documentation text that is generated.

Installation

Installation and upgrading has been designed to be quick and easy. Just quit all running instances of Visual Studio and run the installer executable included in your download. (There is usually no need to uninstall any version of Atomineer prior to installing another version unless you wish to change the install location).

The default installation location will be to 'My Documents', the standard Visual Studio add-in location. (The installer allows you to choose a new location. Note that this location is used for storing preferences, so it can't be a protected location such as in 'Program Files').

Click Install to install the add-in.

For first-time installs, the Quick Setup Wizard will appear, allowing you to configure Atomineer by clicking on example documentation comments that suit your requirements. (Note that these are just some of the most popular options. You can fine-tune these settings at any time in future from the Atomineer Options)

The next time you run Visual Studio the Addin will auto load and place a new Atomineer menu on the Tools menu.


Hot-keys
The add-in will automatically set up hot-keys for the primary commands (but only if they are not already in use for any other commands). However, if you wish to change the default hot-key assignments, follow these steps:

  • In Visual Studio, go to Tools => Options
  • Find the Environment\Keyboard section
  • In "Show commands containing" type "Atomineer"
  • The Atomineer commands will be listed. To add a hot-key binding, select a command, click in the "Press shortcut keys" field and press the key combination you wish to use to execute the command. When you are happy with the hotkey, click Assign.

Multi-user Installation
If you wish to deploy the Atomineer 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):

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

Atomineer uses a 'search path' when loading preferences/rules, which allows you to place your customisations into source control. This is highly recommended for use in a team environment. Please see below for details.


Unattended Command-line Installation
You can install or uninstall Atomineer from the command line for easier deployment to teams. The options are:
AtomineerUtilsSetup.exe -iInstall to the default location, or upgrade an existing installation in-place.
AtomineerUtilsSetup.exe -i <folder-path>Install to the given folder path (must be on the local hard drive, and not in a protected location like Program Files. This option should only be used for first-time installs).
AtomineerUtilsSetup.exe -uUninstall.

Please note:

  • Installation/Uninstallation will not proceed if Visual Studio is running.
  • On Vista/Win7, UAC will need to be disabled to avoid the UAC prompt stalling the unattended installation (in this case, the user will have to manually choose the 'yes' option before the installation will complete).

Atmel Studio 6.0

Atomineer is fully compatible with Atmel Studio.


Disabling or Uninstalling Atomineer Pro Documentation
Atomineer 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 Atomineer add-in.

To uninstall Atomineer, run the AtomineerUtilsSetup.exe and choose the Uninstall option. This will give you the option of retaining user files (preferences and rules files), or completely uninstalling Atomineer and all the configuration files permanently.

(Note that you do not need to uininstall Atomineer to upgrade to a newer version, unless you intend to move the installation to a different location).



Command: Add Doc Comment

Default hot-key:Ctrl+Shift+D

This command creates or updates a Documentation XML, Doxygen, Qt or Javadoc-compatible description comment block for C#, C++/CLI, C++, C, Java, Visual Basic or UnrealScript code.

Usage
Place the cursor in an appropriate line:

  • Anywhere in the first line of the file (for a file header)
  • Anywhere in the whitespace at the end of the file (for a file footer)
  • Anywhere in the first line of a "code element" (namespace, macro, typedef, struct, enum, class, interface, function, property or variable definition, etc) 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.

For example, the following function documentation headers were completely auto-generated. (Note that these examples are in the default Atomineer style. The style is highly configurable (see some examples of different styles).

	////////////////////////////////////////////////////////////////////////////////////////////////////
	/// <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 of the auto-generated documentation text, see: Documentation XML format comments and Doxygen format comments.

Generating new documentation
Atomineer uses thousands of special rules to generate meaningful documentation based on the types of code elements (e.g. constructors/destructors/operators, event handlers, indexers, etc), commonly used names (from .NET, MVC, MVVM, MFC, Qt, stdlib, etc e.g. ToString, GetHashCode), common naming styles (e.g. GetXxx, SetXxx, XxxForm, XxxException), common abbreviations (ptr -> pointer, wnd -> window) and the context in which an element is used (e.g. 'sender' in an event handler, or the number of parameters to an Equals method, etc). 'Perfect' documentation can't always be achieved, but Atomineer attempts to provide the best documentation it can so that even though you will need to finish the comments yourself, the typing involved is minimised.

For example, Atomineer provides:

  • (For doxygen only) the declaration of the code element being documented.
  • A brief summary of the code element, containing an auto-generated description.
  • Author and current date.
  • All parameters, generic type parameters and any return value are entered into the comment as required, with meaningful auto-generated descriptions where possible.
  • Atomineer will attempt to keep related blocks of entries tidy by grouping them together and formatting them with indentation and word-wrapping).
  • The cursor is positioned in the <summary> section of the comment, ready for you to describe your code.

The add-in uses some very powerful systems for generating the documentation automatically:

  • A user-editable "rules" system containing thousands of rules generates meaningful documentation for code elements based on common naming practices, naming conventions, and can even combine information on parameter and return types (etc) with the naming to deduce more useful documentation.
  • If existing documentation is available on an overridden base class method/property or an implemented Interface method/property, it will be copied into your new documentation comment. [*]
  • If existing documentation is available on other overloads of a method, the docs from the best-match overload will be copied. [*]
  • If a parameter has been used and documented in other methods of a class, the documentation from the best match will be copied. [*]
  • All exceptions thrown within a method will be documented automatically.

[*]   Please note: The three features marked above rely on the Visual Studio Intellisense system. If this is disabled, your documentation is not in Documentation XML format for use by Intellisense, or the intellisense information is not available (e.g. in C, Java or UnrealScript code, and sometimes in C++, C# or VB if the code hasn't compiled successfully) then Atomineer will have no choice but to fall back to its regular auto-documentation generation algorithm.

All of the above is configurable - The style of blocks, the entries they contain and their ordering, indentation styles and word-wrap, and use of blank lines (both within the comment and between the comment and any surrounding code).

In addition, if 'Add Doc Comment' is executed in any other text-based file format, Atomineer will add a file header, footer, or 'catch all' comment to the file. These are somewhat simpler than the documentation comments that are generated for the file formats listed above, but can still save considerable time and effort when documenting other source files (SQL, XML, HTML, python, ruby, etc). Note that these comments will not be updated by Atomineer, only created.

Updating existing documentation comments
If a documentation comment already exists, it will be parsed and updated - for example if you add a new parameter to a method, remove an exception thrown in your method, or change a Property by adding a get/set accessor, the existing comment will be updated to reflect the new details, effortlessly keeping the comment in sync with the code. This feature can also serve to automatically convert most existing Documentation XML/Doxygen comments into the Atomineer format (see below for more details).

In addition, the block will be (optionally) reformatted to keep it tidy:

  • Documentation entries will be formatted into a consistent ordering, grouped together into related blocks, with optional blank lines between them. Within each block of entries (e.g. <param> lists), the text for the entries can all be indented to start at the same column to enhance readability.
  • 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). To deliberately force a new line, you can also end the previous line with two spaces.
  • 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.
  • Documentation comments can include a mixture of XML and/or HTML elements. However, you may also wish to use <, > or & characters in descriptions and code examples. Atomineer will process the entry text, converting these special characters into the entities '&lt;', '&gt;', and '&amp;' if necessary. (This feature can be disabled in the preferences if you do not wish to use the text in external documentation generation applications, to keep the code comments more readable). In addition, < and > characters within XML 'cref' attributes will be converted to { }, following Microsoft's documentation XML guidelines.
  • 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. The number of blank lines to enforce after {, #region, #if, public:, private:, protected can also be configured.

'Deleted' entries
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 execute the Doc Comment command a second time, any such 'deleted' lines will be automatically removed to save you having to manually clean up the comment.

Additional 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 Atomineer to keep everything tidy.
  • If you wish to re-generate the auto-doc text for any entry in your comment, or the entire comment, simply delete the entry/comment and execute Add Doc Comment again to update it.
  • 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, Documentation XML 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 into Doxygen format.
  • Note that most documentation addins use the Intellisense system within Visual Studio to get information on the code element, so they can fail if your code is not in a compilable state (which can be much of the time if you document as you write the code). Atomineer only uses Intellisense to augment its own built in parser, so it is usually able to correctly handle code even if it is currently not in a compiled/compilable state.

Configuring Atomineer Documentation

Changing the comment layout style and generated documentation text

The style of the comment blocks is extremely configurable. High-level settings can be changed using the Atomineer Options (available from the Tools > Atomineer Pro Documentation 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 Rules Guide sections for more details. There are also some detailed tutorials below which will help you to understand how to get the best results from Atomineer.

Finally, please email Atomineer support if we can be of any assistance in achieving the format you require, and we'll be happy to help.

Set-up Tutorials
[PDF]    Tutorial - Configuring Atomineer.pdf  (1.3MB)
[PDF]    Tutorial - Making the Most of Atomineer.pdf  (0.9MB)

Converting documentation from an old format
If you have existing documentation comments in a format that Atomineer can parse, you can configure Atomineer to read it and convert it to your new Atomineer style. For full details on the various conversion tools provided by Atomineer, please see this page.

Helping Atomineer to parse your code better
Occasionally, Atomineer hits something that confuses it, resulting in a lower quality of automatic documentation than expected. Typical examples are when a typedef or #define macro are used to represent special types in your code - Atomineer only parses the code near the location you wish to document, so it has no way of understanding what these special code symbols represent.

In these cases, Atomineer allows you to apply preprocessing regular-expression replacements to the code as it is parsed so you can aid Atomineer. Full details are here.


Documentation Comment and Regular Comment editing enhancements

Atomineer can optionally track changes within comments and doc comments as you edit them, and offers the following enhancements to the standard Visual Studio behaviour. These are enabled by default, but can be disabled if you wish - see the 'typing aids' box on the first tab of the Atomineer Options.

For .NET projects, Visual Studio has a handy feature: If you type the start of a documentation comment block (/// in C#, or ''' in Visual Basic) above a code element, then it automatically creates a skeleton comment block. Atomineer extends this behaviour in the following ways:

  1. The Atomineer feature works in all supported languages, not just the .NET languages.
  2. The comment block is generated using the Atomineer documentation engine, so the comment uses your configured comment style, and of course all the auto-generated documentation is filled in for you. It works equally well for Doxygen, Qt, JavaDoc, and XML documentation.
  3. The comment block will be indented to the same level as the code element it documents, rather than being dumped at the place where you typed the /// or ''', and the other Atomineer formatting helpers (such as controlling the number of blank lines between code elements) will all apply as normal.

In addition, Atomineer offers enhanced editing within /// (or ''' in Visual Basic) Documentation Comment blocks and any regular comment blocks made up of single-line comments (// in C#, C++, C, Java and UnrealScript, or ' in Visual Basic). These features help you edit the comment body text without having to continually insert and delete comment // or ' prefixes by hand to keep the comment block tidy. These typing aids include:

  1. When you press Return/Enter to insert a new line in a comment, Atomineer will automatically extend the comment onto the new line, duplicating the comment header and indentation from the previous line so that you can continue typing within the comment without having to manage the comment and text indentation. If you wish to exit this 'comment editing mode', press Return twice in a row (the first press will extend the comment, and the second will remove the comment header to leave you on a blank line).
  2. If the current line of your comment seems to start with what looks like a bullet-point (-, *, +) or a numbered list entry (e.g. 1) 2) 3) or 1. 2. 3. or a. b. c. etc), Atomineer will automatically extend the list by entering the next bullet/number on the new line.
  3. When typing in comment block, if you press Delete to delete the newline at the end of a line, Visual Studio will append the following line. If the following line continues the comment block, Atomineer will strip the indentation and single-line-comment prefix to concatenate the comment body text in a cleaner way.
  4. When pasting text into a comment block, Atomineer will automatically reformat it as appropriate to integrate it into the destination comment: Plain text will be converted into comment text; Comment text is converted if necessary between normal and doc-comment formats; code examples (that include a mixture of text and comments) are embedded into the destination comment as a code example, retaining the original prefixes on comment lines. (Note: This ony happens if you paste into a commented line - pasting on a blank line adjacent to a commented line will not apply the reformatting. If the paste-reformatting produces an undesireable result in any case, simply undo once to remove the Atomineer reformatting and leave the text as it would normally have been pasted).

Notes:

  • To use the standard Visual Studio behaviour to 'exit the comment' when pressing Enter, press it twice in a row, or type a Shift-Enter (add a newline at the current cursor position) or Ctrl-Enter (add a newline before the current line).
  • If you enable/disable any of these features, you will need to execute 'Add Doc Comment' once (or restart Visual Studio) before the change to keypress handling will take effect.
  • Due to the way Visual Studio handles keypresses, this feature may interfere with, or be affected by, other installed addins that also process Enter keypresses within comments. If this occurs you can reconfigure Atomineer (or the other addin) to disable the clashing feature and restart Visual Studio. Where possible Atomineer tries not to interfere with other addins, but there is one known issue:
    • Visual Assist X has an option, (Advanced > Corrections : Auto-extend multi-line comments), which provides exactly the same new-line behaviour in comments as Atomineer. Unfortunately these two features will result in the comment prefix being added twice on each line. The recommended solution is to disable the Visual Assist X feature (as it operates in isolation, while Atomineer offers many typing aids that are enabled/disabled together).

Command: Documentation Viewer

Default hot-key sequence: Ctrl+Shift+A, Ctrl+Shift+V

This Atomineer command opens a documentation viewer window. This displays documentation comments in a human readable style similar to the sort of output you can generate with tools like Sandcastle, Doxygen, and JavaDoc.

If you open the viewer, it will automatically display any available documentation for the nearest code element as the text cursor is navigated through your source code. (Please note that this feature is not currently available in C/C++ header files, nor for end-of-line comments)

The viewer handles common documentation markup including basic HTML elements such as <br/> <p/> <para/> <c/> <code/> <b/> <i/> <strong/> <h1/> etc.

Right-click anywhere in the viewer window to show options including:

  • Select from a range of pre-defined templates. These change the documentation layout and fonts used to emulate different styles that can be produced by tools like Sandcastle, Doxygen and JavaDoc.
  • Scale all the text in the window to a size that suits your preferences.

Your choices will be automatically saved so that Atomineer uses the same options the next time you start Visual Studio.

The viewer display will automatically reformat to suit the window size, and can be resized and docked just like any other Visual Studio tool window.

Important notes:

  • This feature is a text viewer rather than a 'WYSIWYG preview'. The formatting of the text will not match the output of external documentation generation applications or web browsers
  • The documentation shown in the viewer is only that contained within the documentation comment. Atomineer will not augment it with other information (such as lists of class members), as the process of building this 'comprehensive' documentation is time consuming, which defeats the primary purpose of providing an instantaneous and lightweight viewer.
  • The viewer is not currently interactive - links will be displayed syntax-coloured but they cannot be clicked to view documentation elsewhere in the system - documentation pages are only shown for code elements as you move your cursor within the source code.

Command: Document All in this Scope

Default hot-key sequence: Ctrl+Shift+A, Ctrl+Shift+S

This command searches a file, namespace, class, interface, struct, or enum scope using Atomineer's built in code parser, and applies the Add Doc Comment command to each major code element within it. (Note that it does not recurse into nested (child) scopes (so you may have to run it several times to document a whole file if it contains several classes).

Usage
To document all code elements at global scope in a file, place the cursor in the very first line of the file and execute the command.

To document all code elements within a specific scope, place the cursor in the declaration that introduces the scope (i.e. somewhere in the line with the 'namespace', 'class' (etc) text) and execute the command.

Description
When you execute the command, the code within the next scope (i.e. for C-style languages, 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. This processing can be undone.

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 Atomineer format,
  • Quickly update existing documentation after changing the Atomineer 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.

Important Notes

  • This command is affected by the 'restrict documentation by access level' preference. By default, all code elements will be documented. However, in C#, Visual Basic and Java code, this option can be used to restrict the generated documentation so that it only applies to code elements with the correct access level. Generally this is used to apply documentation to just the public members of a library, or suppress documentation of private members while allowing public/protected/internal members to be documented. Please note that as C++ access levels are not specified within the code element declaration, this option is unavailable for C++.
  • This command operates in two modes. Initially it will try to use Visual Studio's Intellisense/CodeElement database to determine what to document (This mode may fail when the Solution has not been successfully compiled, or where Visual Studio itself does not provide the CodeElement information needed). If this information is unavailable, Atomineer will parse the code in the scope for itself, searching for code elements to document. This makes the command very useful in older versions of Visual Studio, or when your project has not been recently compiled, as it will succeed in conditions where the other Doc All In... commands are unable to operate.

Command: Document All in this File

Default hot-key sequence: Ctrl+Shift+A, Ctrl+Shift+F

This command searches a single source code File (not header files) and applies the Add Doc Comment command to each major code element within it. It is only available for languages for which the required CodeElement (Intellisense) information is available (i.e. it works best for .net languages, and in more recent versions of Visual Studio). It is similar to 'Document all in This Scope', but in files that contain several classes, this will document everything in one pass.

Usage
Place the cursor anywhere in the file and execute the 'Document All in This File' command.

(Note: To document only the members of a single class at a time, use the 'Doc All in Scope' command instead)

Description
When you execute the command, Atomineer will search the Visual Studio Intellisense CodeElement database for all code elements in the current File. It will then proceed to document each in turn.

Progress will be shown in the Visual Studio status line, and you may hold down the Escape key at any time to abort processing. After processing, details of what was documented are reported to the Visual Studio 'Output' window (in the 'Atomineer Pro Documentation' section)

This command can be used in the following ways:

  • Convert legacy comments into the configured Atomineer format,
  • Quickly update all existing documentation after changing the Atomineer block format or preferences,
  • Automate an initial documentation pass on a large codebase.

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.

Important Notes

  • This command is affected by the 'restrict documentation by access level' preference. By default, all code elements will be documented, but this option can be used to restrict the generated documentation so that it only applies to code elements with the correct access level.
  • The command relies on Visual Studio Intellisense information to determine what to process, so in some cases it may not be able to process the code (primarily this depends on the version of Visual Studio in use, whether the solution has been successfully built, and how well Visual Studio supports the code language - it works best with .net languages, and in later versions of Visual Studio). If this command cannot process your code, try the 'Doc all in This Scope' command, as it uses Atomineer's own code parser to find the code elements to document. (This command will be greyed out if Intellisense information is unavailable, but in some circumstances intellisense information can be incomplete, in which case the command may report 'No code elements found to document', or it may only document a subset of the code items present).
  • This command cannot be applied to C++ header files - they will simply be ignored.

Command: Document All in this Project

This command applies 'Document All in this File' to all suitable source code files in a Project.

Usage
Place the cursor anywhere in a source-code file within the project you wish to document, and execute the 'Document All in This Project' command.

Description
When you execute the command, Atomineer will apply 'Doc All in this File' to all Files in the Project containing the currently active source code file.

Progress will be shown in the Visual Studio status line, and you may hold down the Escape key at any time to abort processing. After processing, details of what was documented are reported to the Visual Studio 'Output' window (in the 'Atomineer Pro Documentation' section)

Important Notes

  • Please see the notes on Doc All in this File for details of the commenting operation of this command.
  • Note that processing hundreds or thousands of code elements in a single pass can be quite time-consuming, and requires Visual Studio to work hard (possibly using a lot of memory).
  • Depending on the version of Visual Studio, you may see code windows updating during processing. This is normal behaviour.
  • In Visual Studio versions 2010 onwards, the status line progress indicator can sometimes cease updating, thus making it look as though the processing has locked up. If this occurs, status updates can sometimes be recovered by moving the main Visual Studio window. This lack of feedback does not affect processing, which usually completes successfully in due course.
  • Open files will be processed and left open, and a new undo step will be generated for the changes made. Non-open files will be opened, processed, saved, and closed - no undo will be available in these files. If you wish to review all the changes it is suggested that you check allwork in to source control before executing this command, so that the results can be easily diffed at leisure.

Command: Document All in this Solution

This command applies 'Document All in this File' to all suitable files in a Solution.

Usage
Place the cursor anywhere in a source-code file within the project you wish to document, and execute the 'Document All in This Solution' command.

Description
When you execute the command, Atomineer will apply 'Doc All in this File' to all Files in the loaded Solution.

Progress will be shown in the Visual Studio status line, and you may hold down the Escape key at any time to abort processing. After processing, details of what was documented are reported to the Visual Studio 'Output' window (in the 'Atomineer Pro Documentation' section)

Important Notes

  • Please see the notes on Doc All in this File for details of the commenting operation of this command.
  • Note that processing hundreds or thousands of code elements in a single pass can be quite time-consuming, and requires Visual Studio to work hard (possibly using a lot of memory).
  • Depending on the version of Visual Studio, you may see code windows updating during processing. This is normal behaviour.
  • In Visual Studio versions 2010 onwards, the status line progress indicator can sometimes cease updating, thus making it look as though the processing has locked up. If this occurs, status updates can sometimes be recovered by moving the main Visual Studio window. This lack of feedback does not affect processing, which usually completes successfully in due course.
  • Open files will be processed and left open, and a new undo step will be generated for the changes made. Non-open files will be opened, processed, saved, and closed - no undo will be available in these files. If you wish to review all the changes it is suggested that you check allwork in to source control before executing this command, so that the results can be easily diffed at leisure.

Command: Document All in Chosen Files

This command applies any of the other Doc All In... commands, first allowing you to set a number of additional options controlling exactly which file(s) should be processed, which code elements to process, and how the processing should be customised.

Usage
Place the cursor anywhere in a source-code file within the project you wish to document, and execute the 'Document All in Chosen Files' command.

Description
When you execute the command, Atomineer will show an options dialog, with 4 sections.

  • In the first section, choose the main set of files to process (the current file, all open files, all files in the current Project, all files in the current Solution)
  • If more than one file is selected, the second section allows you to apply filtering to further restrict which files are processed:
    • A regex filter can be applied. Any file whose leaf-name matches the regex will be processed; any which does not match will be skipped. For example, .*\.cs will only process files with ".cs" file extension; Database\.* only process files with a "Database" prefix.
    • Partial classes. Atomineer can be instructed to only document a partial class if the class name matches the filename (e.g. 'partial class MyClass' will be processed in 'MyClass.cs' but not in 'MyClass.Statics.cs', ensuring that the class itself is only documented in a single location. Note that the contents of the class will still be documented in these files)
    • Read-only files can be skipped. This usually allows you to only document files that are currently checked out from source control (depending on how your source control provider operates).
  • Atomineer normally documents all code elements in a file. However, sometimes you might like to only update existing comments to 'refresh' them or convert them to a new style. At other times you might like to leave existing documentation alone, and only add new comments for code elements that were previously undocumented. This can help you to avoid touching files unnecessarily, and of course significantly speed up processing if only a few elements need to be documented.
  • Finally, you can control whether or not file headers should be added to the processed files, and the generation of author/date entries can be temporarily suppressed during processing.

Progress will be shown in the Visual Studio status line, and you may hold down the Escape key at any time to abort processing. After processing, details of what was documented are reported to the Visual Studio 'Output' window (in the 'Atomineer Pro Documentation' section)

Important Notes

  • Please see the notes on Doc All in this File for details of the commenting operation of this command.
  • Note that processing hundreds or thousands of code elements in a single pass can be quite time-consuming, and requires Visual Studio to work hard (possibly using a lot of memory).
  • Depending on the version of Visual Studio, you may see code windows updating during processing. This is normal behaviour.
  • In Visual Studio versions 2010 onwards, the status line progress indicator can sometimes cease updating, thus making it look as though the processing has locked up. If this occurs, status updates can sometimes be recovered by moving the main Visual Studio window. This lack of feedback does not affect processing, which usually completes successfully in due course.
  • Open files will be processed and left open, and a new undo step will be generated for the changes made. Non-open files will be opened, processed, saved, and closed - no undo will be available in these files. If you wish to review all the changes it is suggested that you check allwork in to source control before executing this command, so that the results can be easily diffed at leisure.

Command: Delete Documentation from this File

This command deletes all documentation comments from the active source code file.

Usage
Place the cursor anywhere in a source-code file you wish to process and execute the 'Delete Documentation from this File' command.

Description
When you execute the command, Atomineer will process the active source code file, removing any block documentaiton comments (but not end-of-line comments) that either use the /// (C-style languages) or ''' (Visual Basic) line prefixes, or your configured Atomineer comment style. This operation can be undone.

Important Notes

  • Please make absolutely sure that you wish to delete all documentation comments before confirming this action. On completion, review the results to ensure that Atomineer has only removed those comments that you intended - It will preserve file header comments and non-documentaiton comments, but it is possible that it might remove something you did not intend. You can undo to restore the previous contents if you are unhappy with the results.
  • Note that this command will remove comments that match your configured Atomineer documentation comment format. If you use an unusual or nonstandard format it is possible that Atomineer might only partially remove some comments, or may inadvertently remove non-documentation comments. Please review the results and discontinue use if your comment format causes side effects with this command.

Command: Align Code Into Columns

Default hot-key sequence: Ctrl+Shift+A, Ctrl+Shift+C

Quickly align text patterns into tidy columns and tables. This can be used to align assignments, commas, arithmetic/logical/bitwise/comparison operators, brackets, strings, numbers, variables and keywords. Alignment can be used to significantly improve code readability and clarity in repetitive blocks.

Usage
There are two ways to use this command:

  • Place the cursor next to a symbol that you wish to align to, and execute the command. Atomineer will search up and down from this starting point to auto-discover the block of similar code lines to be aligned.
  • Select a block of lines to be processed, starting the selection from the symbol you wish to align to, and execute the command.

Description
When executed, this command will look at the closest text to the left or right of the current cursor position (or the top point of the selection). It then searches the block of lines to be processed for similar lines, and inserts tabs/spaces into these lines to align the matches into a column.

When used with a selected block, lines that don't match the pattern (e.g. blank lines) will be skipped, allowing tables with gaps in them to be processed in one pass.

For example (the red line shows where the cursor can be placed when executing the command):

Align before assignments
int age |= 5;
int height |= 97;
int age    = 5;
int height = 97;
Align after assignments
int age =| 5;
int height =| 97;
int age =    5;
int height = 97;
Align after commas
AddUser("Administrator",| "bunny");
AddUser("John",| "abc");
AddUser("Susanna",| "password");
AddUser("Administrator", "bunny");
AddUser("John",          "abc");
AddUser("Susanna",       "password");
Align before numbers
int[] values = 
{
    4379, |81,
    323692, |1079233,
    12, |36846,
}
int[] values = 
{
    4379,   81,
    323692, 1079233,
    12,     36846,
}

By applying the command several times (left to right) you can align multiple parts of the lines:

Align variable names +    
Align assignments +
Align comments
byte flags = 0; // options
int volume = 72; // m3
long displacement = 134; // in water
byte flags        = 0;   // options
int  volume       = 72;  // m3
long displacement = 134; // in water
Align after colons +
Align breaks
case Left: t = "left"; break;
case Top: t = "top"; break;
case Right: t = "right"; break;
case Bottom: t = "bottom"; break;
case Left:   t = "left";   break;
case Top:    t = "top";    break;
case Right:  t = "right";  break;
case Bottom: t = "bottom"; break;

The command will also align equivalent code elements such as logic operators, work on non-code text such as XML or CSV data, and tidy up code indentation:

Align logic operators
if (readFile &&
    container.IsEmpty &&
    file.IsOpen ||
    reader != null)
if (readFile          &&
    container.IsEmpty &&
    file.IsOpen       ||
    reader != null)
Align words +
Align XML element ends
<rec cn='Pitson' cc='PT' val='12'/>
<rec cn='Vea' cc='VE' val='7'/>
<rec cn='Lardy' cc='LAL' val='149'/>
<rec cn='Pitson' cc='PT'  val='12'  />
<rec cn='Vea'    cc='VE'  val='7'   />
<rec cn='Lardy'  cc='LAL' val='149' />
Align to tidy up indentation
      int i = 0;
  int j = 1;
    int k = i + j;	
    int i = 0;
    int j = 1;
    int k = i + j;

Making the most of Alignment
Arguably one of the best features of the Visual Studio editor is also one of its least-known features. Hold down Alt while dragging (or use Alt+Shift with the cursor keys) and the selection becomes an arbitrary rectangular region (column) within the code. These columns can be copied and pasted, deleted, and overtyped (as you type, the text is repeated into every line in the selection). Once you have aligned the code into columns with Atomineer, this feature makes editing tables of information incredibly fast and easy, as you can move entire columns, add and delete columns as easily as though you were editing a single line of text. This feature is incredibly powerful once you get used to it, and can save a huge amount of time.

Preferences
When inserting whitespace, tabs or spaces will be inserted based on your Visual Studio preferences. However, there is one dedicated preference (on the 'Misc' tab) for this command: When aligning code to a column, it can be aligned to any column (using spaces as necessary to minimise the inserted whitespace), or to the next tab-column (using only tabs).

NOTES:

  • The automatic block detection works best on blocks of code separated by blank lines. If you don't separate blocks in this way, you may find you need to explicitly select the block to be processed to help Atomineer align the text as required.
  • Although it is targetted at code, this command works on any text, including text within documentation comments, XML or CSV files, etc.
  • The algorithm used by Atomineer is a generalised one. The advantage of this is that it is not limited (e.g. to only aligning assignments), but the compromise of the design is that on occasion you may find an example where Atomineer aligns something you didn't want it to. In these cases, you may need to be more explicit (select only the lines you wish to affect), or apply the alignment by hand.
  • Visual Studio provides automatic formatting as you type - this can remove the extra whitespace provided by the Align Columns command. To avoid this happening, go to Tools > Options > Text Editor > {language} > Formatting, and adjust the Spacing options provided. (You can test the results by using the Edit > Advanced > Format Selection menu option to reformat a chunk of code to see how Visual Studio treats the aligned code)

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

Default hot-key sequence: Ctrl+Shift+A, Ctrl+Shift+A

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. 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.


C# Property (VS2008, VS2010)
Before
(A variable)
private int mSpeed;
After 1st execution
(An auto property)
public int Speed { get; set; }
After 2nd execution
(A property with backing field)
public int Speed
{
    get { return(mSpeed); }
    set { mSpeed = value; }
}
private int mSpeed;

C++/CLI Property
Before
public:
private:
  int      mInteger;
  MyClass  mComplexClass;
After
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;

C++ Accessor
Before
public:
private:
  int      mInteger;
  MyClass  mComplexClass;
After
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;


Command: Implement/Declare C++ method

Default hot-key sequence: Ctrl+Shift+A, Ctrl+Shift+I

(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, Atomineer 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

Default hot-key sequence: Ctrl+Shift+A, Ctrl+Shift+X

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 Documentation XML 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

Default hot-key: Ctrl+Shift+C

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 always 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).



Other Menu Items

Atomineer Options...
Shows a dialog for setting the Atomineer Preferences.

Help and User Guide...
Opens the latest version of this User Guide page (direct from the AtomineerUtils.com website) in your default Internet Browser.

Check for updates...
Accesses the AtomineerUtils.com website to determine if a newer version is available for download. (Note: This currently does not work if your PC is behind a Proxy Server).

About Atomineer Pro Documentation...
Shows a dialog providing information on Atomineer, the installed version, and the number of times you have used it.



SuppressUI and AllowUI commands

Suppress user-interface prompting to allow execution from a Visual Studio macro or extension.

Usage
The SuppressUI and AllowUI commands are only available to macros and extensions (and hotkeys). They suppress or allow reporting of any problems via information dialogs. Suppression of this UI allows macros/extensions to automate execution of Atomineer commands without being stalled by dialogs popping up.

Just include the following commands at the start and end of your macro/extension command:

    DTE.ExecuteCommand("Atomineer.Utils.Commands.SuppressUI")

    ... your macro/extension code here ...

    DTE.ExecuteCommand("Atomineer.Utils.Commands.AllowUI")

Note that this option suppresses all UI prompts from Atomineer, but Visual Studio itself may throw up UI in some cases (for example, if it encounters a read-only file - a solution to this is to check out/make all files writable before running your automated task)



Preferences

The Atomineer > 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.

Please note that all of the options in the preferences window provide tool-tips that fully explain what the options do and how to use them - just hover the mouse over any options for a couple of seconds to get more information.

At the bottom of the window are buttons that allow you to reset the options to the Defaults, or run the Quick-Setup Wizard to choose the core format/style of your comments. In the tabs in the main part of the dialog, you can set the following options:

Doc Comment - General settings tab

General Settings:

  • Documentation style: Doxygen (Qt style \command), Doxygen (JavaDoc style @command), Documentation XML (<command>)
  • 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.
  • 'this# phrasing. When describing a method in 'MyClass', you might document the Initialise method as 'Initialises this object', 'Initialises this instance', or 'Initialises this MyClass'. You can choose your preferred phrase for referring to 'this'.
  • Use uppercase for known acronyms. When a method like 'FetchHtmlPage' or 'fetch_html_page' is documented, Atomineer can detect the acronym HTML and document it as 'HTML' rather than 'html'. Disable this option if you are happy to see 'html' in your documentaiton instead. (Note: In the Advanced Customisation tab you can also add your own acronyms and word replacements to extend this behaviour)

Typing Aids: Here you can enable/disable the typing enhancements Atomineer performs in regular and documentation comment blocks.

  • When typing a /// or ''' comment, Atomineer can generate the comment for you, rather than getting the basic skeleton comment that Visual Studio provides by default (C#, VB) or no comment at all (C++, Java, UnrealScript).
  • Maintain indentation/bullets: This option makes it much easier to type long comments, as it makes Visual Studio ignore the // or /// comment headers and treat the text you are typing as a column, rather than moving the cursor back to the left edge of the comment block when you press return. In addition, if you start a bullet or numbered list, Atomineer will automatically add new bullets/numbers when you go to a new line.
  • Convert <>&: This allows you to control the conversion of <, > and & characters into the XML/HTML entities &lt;, &gt;, and &amp; as required to keep your documentation XML legal.
  • Improve formatting of pasted text: If you copy several lines of a comment and then paste them into another comment, Visual Studio will paste verbatim, leaving you to clean up the double comment. Or if you copy some lines of code and paste them into a comment as an example, Visual Studio won't extend the comment to include the pasted text. Atomineer can override this behaviour to provide a cleaner result from these types of Pastes.

Xml-documentation or Doxygen/JavaDoc/Qt options can be set. For Documentation XML:

  • StyleCop compatibility. Enable this option to change the documentation output of Atomineer to a StyleCop-compatible wording and use Stylecop-compatible file headers.
  • Add author and date <remarks> entries: By default, Atomineer will add the author and date to most comments in a <remarks> entry, but this function can be disabled if unwanted.

...or for Doxygen/JavaDoc/Qt:

  • Suppress 'brief' tag: These documentation formats allow the description to be included into the comment without a leading @brief or \brief tag, as long as it is the first text in the comment. Enabling this option instructs Atomineer to suppress the brief tag, and just insert the description at the top of the doc comment.
  • Add declarations/prototypes to comments: Doxygen supports inclusion of the code element declaration within the documentation comment (e.g. @fn int MyFunc(int aParameter);). If you wish to use this command, then Atomineer will automatically copy the code element declaration into the comment for you, keeping it up to date with any changes made to the code itself.
  • Add author/date entries. These control whether or not the author name and/or date are added to documentation comments that Atomineer generates.

The 'comments for single line code elements' options include:

  • Add single-line comments to right of code element. By default, Atomineer will add a single-line comment on the line above any variable that you document. Check this option to tell Atomineer to instead add the comment to the end of the same line (note that this is only fully compatible with Doxygen, as Documentation XML comments must always precede the code element that they document).
  • You can also set a prefix and suffix that are used to frame the description text to form the final end-of-line comment. This allows you to have (for example) a // or /* ... */ style of comment.
  • Starting no earlier than column 'n': This option can be used to force end-of-line comments to the right, which can be useful with lists of member variables to line up all the eol comments into a tidy, readable column.

The final section allows you to control which code elements Atomineer will comment. By default it allows you to document any code element, but it is common for library programmers to only want to add documentation for 'public' members, or for application programmers to supress documentation of private methods. If you wish to do this, set the access level(s) for which you want documentation to be allowed, and Atomineer will ensure that you can only document those code elements. (This is primarily intended for use with the 'Doc all in this Scope/File/Solution' features to stop Atomineer documenting code elements you wish to remain undocumented). Please note that this feature is only available for C#, Visual Basic and Java code (C++ does not specify the access modifier within the code declaration, so Atomineer cannot determine the relevant access level)

Doc Comment - Border Style tab

This section controls the border of the doc comment. 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.

Atomineer 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 Atomineer 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 be a multi-line block (using \n in the text to denote newlines). If you use this, you must use a /** ... */ comment style for Atomineer 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.

Atomineer also has special support for enclosing the documentation comment or entire code element within a code-outlining region. To achieve this, the top separator must start with '#region' or '#pragma region'. To enclose only the documentation comment in the region, set the bottom separator to '#endregion' or '#pragma endregion'. To enclose the entire code element in the region, make sure the bottom separator does not end the region - when Atomineer sees the unterminated region, it will automatically ensure that the #endregion is present at the end of the code element. (Note: usually Atomineer is extremely resilient to unparseable code, but the code must be parseable in this instance for the end-region to be correctly inserted)

Lastly, Atomineer 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

These options control the text formatting within comments. As you change these options, a preview is shown at the bottom of the window so you can (roughly) see the effect - it is usually easier to play with the settings and watch this than to try to work out from descriptions what each setting will do. You can also click 'Apply' and test the settings immediately in Visual Studio to confirm that the settings achieve exactly what you want in your own code.

There are three sets of similar options. The first set applies to 'single entries'. These are entries in the comment that typically only occur once - summary/brief, returns, etc. The second set applies to 'groups of entries' - ones like param, typeparam and exception that often occur as a group of several entries. The final set is (optionally) used in cases where an entire entry will fit onto a single line.

Hint: You can use the quick-setup wizard to choose a style that most closely matches your requirements, and then use these options to tweak the style if required.

The core options are:

  • What to insert between the entry tag and the description text. This controls how much whitespace there is between the tag and text, or can add a newline.
  • What to insert at the start of each new line in the description text. This allows the text block to be left-aligned, indented slightly, or indented so that the text forms a block with each line starting directly below the preceeding line.
  • (DocXML only) What to insert at the end of the text, before the end-tag. Again, this allows the tag to be separated with a small amount of whitespace, or moved onto a new line (left-aligned or lined up below the preceeding line of text)
  • The 'Keep short entries as a single line' check-box allows Atomineer to ignore the above settings if the entire entry is short enough to be added as a single line of text.

The other options available on this page are:

  • 'Word wrap'. With this disabled, Atomineer will leave the line formatting up to you. When it is enabled, Atomineer will word-wrap the text as it updates a comment, to keep it tidy. You can set the word-wrap column relative to the edge of the page, or relative to the left of the comment block (so that all comment blocks are the same width, regardless of their indentation within the code)
  • 'Add blank lines between blocks of entries'. By default, Atomineer will separate each block of ssmiilar entries from the next by adding blank lines. This option disables that feature, to produce a more compact but less readable comment layout. (Note: Comment Templates can be used to specify exactly where blank lines are inserted, if you require more exact control over the layout)
  • 'Align text in group to same column'. When the group formatting options specify that the text should be aligned with the text from the preceeding line, this can be aplied to each entry independently, or to the description text for all the entries in the group as a whole. This group-wide formatting makes the comment much easier to read, but often results in a lot of space being sacrified.

Advanced Customisation tab
The style and layout of doc comments, and the auto-doc text generated can be radically customised by editing the Atomineer Rules. These are described in a simple XML-based form. Rather than editing the raw Rules.xml file, this Options tab allows you to customise specific parts of the rules independently in a set of xml files.

At the top of the tab, you may set the Rules Search Paths, which set Atomineer up to search in multiple locations to find its custom rules and preferences files. The most common uses of this feature are:

  • To allow preferences and custom rules to be stored in a Source Controlled folder
  • To allow teams who share rules via source control to locate their code on different hard drives but still share the same setup (e.g. a path like "C:\Code;D:\Code")
  • To use different commenting styles for different solutions or projects, e.g. Doxygen commenting for C++ projects and DocXml for C# projects.

You may set one or more paths separated by semicolons (for example 'C:\Code', 'C:\Code;D:\Code').

These paths can also include the %solutionPath%, %solutionName%, %projectPath% or %projectName% variables (or any operating system environment variable enclosed in % characters (e.g. %AppData%)). These are expanded to the full path of the active solution/project folder or their leafname as appropriate, allowing every Visual Studio project to optionally contain an independent set of Atomineer rules/prefs xml files that are project-specific. As you comment your code the appropriate settings will be used for the active project/solution. This makes it much easier to use different comment formats or rules for different programming languages. (For example, '%projectPath%\Atomineer;C:\Code\Atomineer' will first look in the current project's root folder for an Atomineer folder containing Prefs or Rules files; if not found, it will then look in the C:\Code\Atomineer folder, and then finally look in the default location).

The suggested approach for using this with C++ and C# projects is to set the 'default' Atomineer preferences appropriately for the most commonly used language (e.g. C#) and then copy your special (C++) settings only into C++ projects. This minimises the effort involved in duplicating settings into projects.

Below the search path field are a number of buttons. Each allows you to export one section of the rules to a custom file, and then edit it. The first time you click each button, the rules section will be exported to a separate file in the first folder (that does not include any %variables%) listed on your Rules Search Path. If the search path is not set, they will be exported in the Atomineer install folder. Once customised, the button text will turn green and clicking it will simply open the custom rules for editing.

(If you wish to use a custom format for different projects, then set up the preferences as you wish, export them in this way, and then move the reuslting files into the solution-relative or project-relative search folder. You of course will no longer be able to edit those files in the Atomineer options dialog)

Each customisation file contains a lot of documentation in the form of embedded XML comments and examples that show you how to write your own rules to augment the default Atomineer behaviour. Please see the Rules Guide for full details on how to edit your own custom rules.

The last section of this Tab allows you to move the storage location for the block comment style preferences into a set of custom files. These preferences will continue to be edited as normal in the preferences dialog, but will now be stored on your Rules Path, making it possible for them to be held under Source Control. You can move these files anywhere you like as long as they can be found on the Rules Path you set at the top of the Tab. (As described above, these files can be used with %variables% in your path to apply different comment styles for each of your solutions or projects)

More information on custom templates and rules can be found below.

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 Atomineer preferences.

'Menu Items' allows you to hide menu items for Atomineer 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.

  • Optionally convert tabs into spaces, using columns at a given character spacing
  • Remove any "excess" leading whitespace. This unindents the copied block of text back to the left hand side of the page without detroying the relative indentation of the lines.

'Create Property/Accessor command' allows you to set a (C#, C++) member variable and (C++) method style templates. These are used in the following ways:

  • They specify a prefix and suffix to strip off a member variable to determine the actual name of the value (e.g. m_Speed -> Speed/GetSpeed).
  • For C#, they specify how to generate a backing field when converting an auto property into an explicit one.
  • For C++, they specify how to name the getter/setter methods that are generated, allowing different styles and even different languages to be used.

The core of the templates is the special text 'VarName' which is a placeholder for the actual variable name. This may have an arbitrary prefix and/or suffix. In addition, the casing style (VarName or varName) controls the casing of the result. The combo boxes supply predefined examples, or you can type your own custom templates in instead.

'Implement/Declare C++ method' command allows you to configure aspects of the implementation behaviour:

  • Switch to the newly implemented code after implementing: If enabled, the command will leave you in the file where the new code has been added (to allow you to immediately edit the result). If disabled, you will remain in the file where the command was executed (to allow many methods to be conveniently implemented/declared in a row)
  • When implementing a method, you can choose to automatically add a DocComment to it, using any single-line comments above the declaraton to provide the brief/summary description.


Doc Comment Rules and Templates

The DocComment output of Atomineer is extremely configurable via a set of simple Xml files. A full guide on creating these files is available here.

Keeping custom preferences and rules in Source Control
For easier team deployment you may wish to check your rules into your source control system. Atomineer has a
Rules Search Path preference that allows you to relocate your custom rules/prefs files anywhere you wish. You can set multiple folders in this path so that each developer can map their workspace to a different drive or folder and still share a global team setup.

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

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