08/04/13

AtomineerUtils - Documentation Comment add-in for Visual Studio (2010,2008,2005)

Installation
The download includes an installer. Just quit all running instances of Visual Studio, run the installer executable, and hit the install button. For first-time installs, the Quick Setup Wizard will appear, allowing you to configure AtomineerUtils simply by clicking on example documentation comments that suit your requirements. (You can refine or re-choose these settings at any time via the AtomineerUtils Options later) 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).

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 hotkey 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 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 In addition, AtomineerUtils uses a 'search path' when loading preferences/rules, which allows you to place your customisations into source control. See below for details.

Disabling or Uninstalling AtomineerUtils 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. (Note that you do not need to uininstall AtomineerUtils to upgrade to a newer version - just install over the top). To uninstall AtomineerUtils, 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 AtomineerUtils and all the configuration files permanently.

Command Reference
1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. Add Doc Comment for a code element Documentation Comment editing enhancements Document all in this scope Create C# or C++/CLI Property or a C++ Accessor from a member variable declaration Implement/Declare C++ method Open C++ Source or Header Hide DocComments using Outlining Hide Attributes using Outlining Copy As Text Word Wrap comment Other Menu Items Suppressing and Allowing User Interface prompting in Macros Preferences controlling the behaviour of the Atomineer commands Doc Comment Rules and Templates controlling the layout of comments and the generated documentation text

Command: Add Doc Comment

file:///C:/Users/aarevalo/Desktop/AtomineerUtilsPro743/Help/UserManual.html 1/11

08/04/13

AtomineerUtils - Documentation Comment add-in for Visual Studio (2010,2008,2005)

Default hot-key: Ctrl+Shift+D This command creates or updates a Documentation XML, Doxygen or Javadoc-compatible description comment block for C#, C++/CLI, C++, C, Java 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 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 AtomineerUtils style. The style is highly configurable (see some examples of different styles).
/ / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / /< s u m m a r y >E v e n th a n d l e r .C a l l e db yt h eT a s k L i s t C t r lf o rK e y D o w ne v e n t s .< / s u m m a r y > / / / / / /< r e m a r k s >J a s o nW i l l i a m s ,1 2 / 0 4 / 2 0 0 9 .< / r e m a r k s > / / / / / /< p a r a mn a m e = ' s e n d e r ' > S o u r c eo ft h ee v e n t .< / p a r a m > / / /< p a r a mn a m e = ' e ' > E v e n ti n f o r m a t i o n .< / p a r a m > / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / v o i dT a s k L i s t C t r l _ K e y D o w n ( o b j e c ts e n d e r ,K e y E v e n t A r g se ) { } / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / /< s u m m a r y >I n i t i a l i s e st h ef i l eb u f f e r .< / s u m m a r y > / / / / / /< r e m a r k s >J a s o nW i l l i a m s ,1 2 / 0 4 / 2 0 0 9 .< / r e m a r k s > / / / / / /< e x c e p t i o nc r e f = " N o t I m p l e m e n t e d E x c e p t i o n " >T h r o w nw h e nt h er e q u e s t e do p e r a t i o ni s / / / u n i m p l e m e n t e d .< / e x c e p t i o n > / / / / / /< p a r a mn a m e = " f n a m e " > F i l e n a m eo ft h ef i l e .< / p a r a m > / / /< p a r a mn a m e = " b u f f S i z e " > S i z eo ft h eb u f f e r .< / p a r a m > / / /< p a r a mn a m e = " r e s e t C a c h e " >t r u et or e s e tc a c h e .< / p a r a m > / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / p u b l i cv o i dI n i t F i l e B u f f ( s t r i n gf n a m e ,i n tb u f f S i z e ,b o o lr e s e t C a c h e ) { t h r o wn e wN o t I m p l e m e n t e d E x c e p t i o n ( ) ; } / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / /< s u m m a r y >G e t so rs e t st h ef o r e g r o u n dc o l o u r .< / s u m m a r y > / / / / / /< v a l u e >T h ec o l o u ro ft h ef o r e g r o u n d .< / v a l u e > / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / p u b l i cC o l o rF g C o l o u r{g e t{ } ;s e t{ }}

For more examples of the auto-generated documentation text, see: Documentation XML format comments and Doxygen format comments. Generating new documentation AtomineerUtils uses hundreds 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, MFC, 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 AtomineerUtils attempts to provide the best documentation it can so that even when you need to finish the comments yourself, the typing involved is minimised. For example, AtomineerUtils Pro 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. file:///C:/Users/aarevalo/Desktop/AtomineerUtilsPro743/Help/UserManual.html 2/11

08/04/13

AtomineerUtils - Documentation Comment add-in for Visual Studio (2010,2008,2005) descriptions where possible. AtomineerUtils will attempt to keep related blocks of entries tidy by grouping them together and formatting them with indentation and wordwrapping). 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 ab ove rely on the Visual Studio Intellisense system. If this is disab led, your documentation is not in Documentation XML format for use b y Intellisense, or the intellisense information is not availab le (e.g. in C or Java code, and sometimes in C++) then AtomineerUtils will have no choice b ut to fall b ack 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, AtomineerUtils 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 AtomineerUtils, 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 AtomineerUtils 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. AtomineerUtils 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:
/ / / # # #< p a r a mn a m e = ' v a l u e ' > T h i sp a r a m e t e rh a sj u s tb e e nd e l e t e d < / p a r a m >

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 b lock of lines commented-out with single-line comments - //), the comment will b e 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 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 b e preserved. By default, Documentation XML format will b e generated, b ut 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 compilab le state (which can b e much of the time if you document as you write the code). AtomineerUtils only uses Intellisense to augment its own b uilt in parser, so it is usually ab le to correctly handle code even if it is currently not in a compiled/compilab le state. Changing the comment layout style and generated documentation text
file:///C:/Users/aarevalo/Desktop/AtomineerUtilsPro743/Help/UserManual.html 3/11

08/04/13 AtomineerUtils - Documentation Comment add-in for Visual Studio (2010,2008,2005) 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 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 Rules Guide sections for more details, and mail support if we can be of any assistance in achieving the format you require. Converting documentation from an old format If you have existing documentation comments in a format that AtomineerUtils can parse, you can configure AtomineerUtils to read it and convert it to your new AtomineerUtils style. For full details on the various conversion tools provided by AtomineerUtils, please see this page. Helping AtomineerUtils parse your code better Occasionally, AtomineerUtils 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 - AtomineerUtils 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, AtomineerUtils allows you to apply preprocessing regular-expression replacements to the code as it is parsed so you can aid AtomineerUtils. Full details are here.

Documentation Comment and Regular Comment editing enhancements

AtomineerUtils can optionally track changes within comments and doc comments as you edit them, and offers the following enhancements to the basic Visual Studio support. These are enabled by default, but can be disabled if you wish on the first tab of the AtomineerUtils 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. AtomineerUtils extends this behaviour in the following ways: 1. The AtomineerUtils feature works in all supported languages, not just the .NET languages. 2. It works for Doxygen and JavaDoc comments as well as XML Documentation comments. 3. The comment block is generated using the AtomineerUtils documentation engine, so the comment uses your configured comment style, and of course all the auto-generated documentation is filled in for you. 4. 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 '''. In addition, AtomineerUtils offers enhanced editing within AtomineerUtils Documentation Comment blocks and any regular comment blocks made up of single-line comments (// in C#, C++, C and Java, or ' in Visual Basic). This includes: 1. When you press Enter to insert a new line, AtomineerUtils will create a new 'blank' line for you, automatically adding your configured line header and then indenting the cursor within the comment so that it lines up directly under the comment text on the preceeding line. 2. If the current line of your comment seems to start with a bullet-point (-, *, +), AtomineerUtils will duplicate it to automatically extend the bulleted list. Notes: For convenience, single line comments will not b e automatically extended, so pressing Enter at the end of the line will just create a completely b lank line. To make it into a multi-line b lock, type another // or ' and continue the comment on the second line. Thereafter, AtomineerUtils will extend the b lock comment when you press Enter. To use the usual Visual Studio b ehaviour when pressing Enter, hold down Shift (add a newline at the current cursor position) or Ctrl (add a newline b efore the current line) at the same time. If you enab le/disab le any of these features, you will need to execute 'Add Doc Comment' once (or restart Visual Studio) b efore the change to keypress handling will take effect.

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 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), and it does not yet handle all possible code elements (constants/variables, or header file declaraitons being the primary examples that I have yet to add support for) 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 (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. file:///C:/Users/aarevalo/Desktop/AtomineerUtilsPro743/Help/UserManual.html

4/11

08/04/13

AtomineerUtils - Documentation Comment add-in for Visual Studio (2010,2008,2005)

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

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 constreference. 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. Before (C++)
p u b l i c : p r i v a t e : i n t m I n t e g e r ; M y C l a s s m C o m p l e x C l a s s ;

After (C++)
p u b l i c : i n tG e t I n t e g e r ( v o i d )c o n s t v o i dS e t I n t e g e r ( i n tI n t e g e r ) {r e t u r n ( m I n t e g e r ) ; {m I n t e g e r=I n t e g e r ; } ; } ;

c o n s tM y C l a s s& G e t C o m p l e x C l a s s ( v o i d )c o n s t {r e t u r n ( m C o m p l e x C l a s s ) ; } ; v o i dS e t C o m p l e x C l a s s ( c o n s tM y C l a s s& C o m p l e x C l a s s ) {m C o m p l e x C l a s s=C o m p l e x C l a s s ;} ; p r i v a t e : i n t m I n t e g e r ; M y C l a s s m C o m p l e x C l a s s ;

After (C++/CLI)
p u b l i c : p r o p e r t yi n tI n t e g e r {

file:///C:/Users/aarevalo/Desktop/AtomineerUtilsPro743/Help/UserManual.html

5/11

08/04/13
{

AtomineerUtils - Documentation Comment add-in for Visual Studio (2010,2008,2005)

i n tg e t ( ) {r e t u r n ( m I n t e g e r ) ;} v o i ds e t ( i n tv a l u e ){m I n t e g e r=v a l u e ;} } p r o p e r t yc o n s tM y C l a s s &C o m p l e x C l a s s { c o n s tM y C l a s s &g e t ( ) {r e t u r n ( m C o m p l e x C l a s s ) ;} v o i ds e t ( c o n s tM y C l a s s &v a l u e ){m C o m p l e x C l a s s=v a l u e ;} } p r i v a t e : i n t m I n t e g e r ; M y C l a s s m C o m p l e x C l a s s ;

C# (VS2005)
p u b l i ci n tI n t e g e r { [ D e b u g g e r S t e p T h r o u g h ]g e t{r e t u r n ( m I n t e g e r ) ;} [ D e b u g g e r S t e p T h r o u g h ]s e t{m I n t e g e r=v a l u e ;} } [ D e b u g g e r B r o w s a b l e ( D e b u g g e r B r o w s a b l e S t a t e . N e v e r ) ] p r i v a t ei n tm I n t e g e r ;

C# (VS2008/2010)
/ /O r i g i n a lv a r i a b l e p r i v a t ei n tm S p e e d ; / /A f t e ro n ee x e c u t i o n ,a na u t o p r o p e r t y p u b l i ci n tS p e e d{g e t ;s e t ;} / /A f t e rt h es e c o n de x e c u t i o n ,a ne x p l i c i tp r o p e r t yw i t hb a c k i n gf i e l d p u b l i ci n tS p e e d { g e t{r e t u r n ( m S p e e d ) ;} s e t{m S p e e d=v a l u e ;} } p r i v a t ei n tm S p e e d ;

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, 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:
/ /C r e a t e san e wT h i n g u m m yc o n t a i n i n gt h er e q u i r e dn u m b e ro fW o t s i t s T h i n g u m m y* C r e a t e T h i n g u m m y ( C r e a t e I n f o* p I n f o ,i n tN u m W o t s i t s=1 2 )c o n s t ;

file:///C:/Users/aarevalo/Desktop/AtomineerUtilsPro743/Help/UserManual.html

6/11

08/04/13

AtomineerUtils - Documentation Comment add-in for Visual Studio (2010,2008,2005)

Resulting source file implementation (with doxygen-style comment)

/ / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / /\ f nT h i n g u m m y* M y C l a s s : : C r e a t e T h i n g u m m y ( C r e a t e I n f o* p I n f o ,i n tN u m W o t s i t s ) / / / / / /\ a u t h o r J a s o nW i l l i a m s / / /\ d a t e 6 / 6 / 2 0 0 5 / / / / / /\ b r i e f C r e a t e san e wT h i n g u m m yc o n t a i n i n gt h er e q u i r e dn u m b e ro fW o t s i t s / / / / / /\ p a r a m p I n f o I fn o n N U L L ,t h ei n f o r m a t i o n / / /\ p a r a m N u m W o t s i t s T h en u m b e ro fw o t s i t s / / / / / /\ r e t v a l N U L Li fi tf a i l s ,e l s e / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / T h i n g u m m y* M y N a m e s p a c e : : M y C l a s s : : C r e a t e T h i n g u m m y ( C r e a t e I n f o* p I n f o ,i n tN u m W o t s i t s )c o n s t { r e t u r n ( N U L L ) ; }

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. file:///C:/Users/aarevalo/Desktop/AtomineerUtilsPro743/Help/UserManual.html 7/11

08/04/13 will be copied.

AtomineerUtils - Documentation Comment add-in for Visual Studio (2010,2008,2005)

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.

Other Menu Items

AtomineerUtils Options... Shows a dialog for setting the AtomineerUtils Preferences. Help and User Guide... Opens the latest version of this User Guide page (direct from the AtomineerUtils website) in your default Internet Browser. Check for updates... Accesses the AtomineerUtils 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. I hope to rectify this soon). About AtomineerUtils... Shows a dialog providing information on AtomineerUtils, 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. Usage The SuppressUI and AllowUI commands are only available to macros (and hotkeys). They suppress or allow reporting of any problems via information dialogs. Suppression of this UI allows macros to automate execution of AtomineerUtils commands without being stalled by dialogs popping up. Just include the following commands at the start and end of your macro:
D T E . E x e c u t e C o m m a n d ( " A t o m i n e e r . U t i l s . C o m m a n d s . S u p p r e s s U I " ) . . .y o u rm a c r oh e r e. . . D T E . E x e c u t e C o m m a n d ( " A t o m i n e e r . U t i l s . C o m m a n d s . A l l o w U I " )

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. 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 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 file:///C:/Users/aarevalo/Desktop/AtomineerUtilsPro743/Help/UserManual.html 8/11

08/04/13

AtomineerUtils - Documentation Comment add-in for Visual Studio (2010,2008,2005) 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. Live update: Here you can enable/disable the typing enhancements AtomineerUtils performs in regular and documentation comment blocks. Conversion: This allows you to enable or disable the conversion of <, > and & characters into the XML/HTML entities &lt;, &gt;, and &amp; as required to keep your documentation XML legal.

In addition, these Doxygen/JavaDoc-specific options can be set: Doxygen tags can be of the form '\brief' (Qt style) or '@brief' (JavaDoc style) 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 Documentation XML comments must always precede the code element that they document) Suppress 'brief' tag. Doxygen supports the Qt/JavaDoc "AutoBrief" style where the brief description entry does not have a tag introducing it. AtomineerUtils Pro supports this style of JavaDoc/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. 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 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. AtomineerUtils 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 AtomineerUtils sees the unterminated region, it will automatically ensure that the #endregion is present at the end of the code element. (Note: usually AtomineerUtils is extremely resilient to unparseable code, but the code must be parseable in this instance for the end-region to be correctly inserted) 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 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 AtomineerUtils 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: file:///C:/Users/aarevalo/Desktop/AtomineerUtilsPro743/Help/UserManual.html
9/11

08/04/13 AtomineerUtils - Documentation Comment add-in for Visual Studio (2010,2008,2005) The other options available on this page are:

'Word wrap'. With this disabled, AtomineerUtils will leave the line formatting up to you. When it is enabled, AtomineerUtils 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, AtomineerUtils 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 AtomineerUtils 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 contol where AtomineerUtils will look for customisations, allowing you to store these additional files in Source Control ort a shared network drive. Below this are a number of buttons. Each allows you to export one section of the rules to a custom file, and then edit it. (By adding customisations in this way, the AtomineerUtils installer can overwrite the default rules without losing your custom rules). The first time you click each button, the rules section will be exported to a separate file in the first folder listed on your Rules Search Path. If the search path is not set, they will be exported in the AtomineerUtils install folder. Once customised, the button text will turn green and clicking it will simply open the custom rules for editing. Each customisation file contains a lot of XML comments and examples that show you how to write your own rules to augment the default AtomineerUtils 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. 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 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. 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 file:///C:/Users/aarevalo/Desktop/AtomineerUtilsPro743/Help/UserManual.html 10/11

08/04/13

AtomineerUtils - Documentation Comment add-in for Visual Studio (2010,2008,2005) 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 AtomineerUtils 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. AtomineerUtils Pro has a Rules Search Path preference that allows you to relocate your custom rules/prefs files anywhere you wish. In the AtomineerUtils Options, just enter one or more paths separated by semicolons (e.g. "C:\Code; D:\Code") and you can move your custom files to those locations and check them into Source Control. If you augment the rules, please consider emailing me your updated rules file for possible inclusion into following releases.

Copyright 1996-2011 Atomineer. All Rights Reserved. Contact us

file:///C:/Users/aarevalo/Desktop/AtomineerUtilsPro743/Help/UserManual.html

11/11