Atomineer Pro Documentation for Visual Studio

Proud to be a Visual Studio Sim-Ship Partner!

Visual Studio Launch Partner This extension for Visual Studio provides unsurpassed code documentation comment generation and updating, smart word wrapping of text within comments, live typing aids to make editing comments much easier, tools to quickly convert legacy documentation to new formats, a command to instantly align code (such as assignments, parameters and tabular data) into columns, and several handy outlining, code generation and clipboard commands.

(How it works)

Save time - save effort - save money.
Eliminate the drudgery of filling in documentation.
Effortlessly keep code and documentation in sync.
Encourage better coding, naming and documentation practices.
Speed up development and reduce errors with intellisense help on all your own classes and methods.
Easily satisfy Code Analysis and Static Analysis requirements for documentation.
Accelerate editing of comments with automated formatting, word wrapping, pasting and bullet-list entry aids, and live spell checking as you edit comments.

Features in Detail - Document code: better, faster, tidier, cheaper

With a single keypress or menu command, the extension can:

Create or update highly configurable Documentation XML, Doxygen, Qt QDoc, JavaDoc or Natural Docs-format documentation comments for code elements (file, namespace, class, interface, template, struct, enum, variable, property, event, delegate, function/method, etc) in your code. Atomineer will automatically generate a clear starting point for your documentation, with context-sensitive descriptions for all parameters, generic type parameters, thrown exceptions and return codes, using contextual information such as existing documentation from related base class and override methods/properties and existing parameters within the same class, and generating accurate and specialised documentation for thousands of common function, class and parameter types. Comments can be automatically converted between all of the supported formats and from bespoke formats to update legacy documentation to a new standard. It can also optionally reformat the updated text using automated indentation, word wrapping and XML validation/correction to keep your code documentation legal, accurate, informative and tidy with a minimum of effort on your part. An absolutely essential tool for any team wishing to write maintainable code.
Automatically document/convert every code element within a namespace/interface/class/struct/enum scope.
Word-wrap the text in a block comment.
Instantly align similar lines of code (e.g assignments, parameters, etc) into columns to improve clarity, readability and editability.
Hide all documentation comments and/or attribute declarations using Visual Studio's Outlining facility.
Auto-generate a C++/C skeleton implementation (in your source file) from a declaration (in a header).
Open the matching header for a given C++ source file, or the matching source file for a given header.
Add a C++/C declaration to your header for any existing method implementation.
Create C# Auto-Properties, Explicit Properties or C++ Accessor functions from member variable declarations.
Copy code to the clipboard in a clean format ideal for use in applications such as when writing Word .doc Documentation, or emailing examples to team members.

Code Documentation - Why do it?

When programming, understanding what classes and methods are for, how to use them, and how they work is critical for rapid development/maintenance and avoiding bugs due to misunderstandings. It's important to write this information down - to share this knowledge across team, as well as for programmers to recall the fine details of code they haven't touched for a long period.

Many programmers write 'self documenting' code, where clear and descriptive naming conventions make it easier to understand code quickly. Documentation comments take this a step further by summarising that information in a single place rather than having to read through often quite complex source code. In addition, and most importantly, code documentation can tell you the things that 'self documenting' code never mentions:

What exceptions will a method throw?

Can I pass a null in to this parameter?

What is the legal range for an integer parameter?

What is the return value that describes 'not found'?

Writing 'self documenting' code is just the first and most basic step of writing well documented, maintainable code.

In addition, the information from documentation comments can be used by Visual Studio's Intellisense system, with the information you need displayed live in tooltips as you type your client code.

There are also tools such as Doxygen (all languages) and SandCastle (.NET languages) that can be used to generate professional external documentation like that used in MSDN - essential for libraries and other code that will be shipped to third parties, as well as being extremely useful for internal use by your team.

There are just three problems:

Writing documentation can be very time consuming
Programmers usually prefer to write code, so the documentation (if written at all) suffers
Comments easily get 'out of sync' with the code, making them useless or even misleading

Atomineer eliminates these problems:

It minimises the effort involved in documenting. A high proportion of documentation content is repetitive and easily filled in by the computer. Although you often have to add to the comments Atomineer provides, it instantly builds a solid basis for your comment.
It summarises as much information as possible about a code element in a standardised form, making it a quick to read format regardless of which programmer(s) wrote the code.
It keeps the documentation in sync with changes to the code (e.g. when parameters, return values or thrown exceptions are changed in a method, or get/set accessors are added to a property).
In many languages, XML Documentation comments are picked up by Visual Studio and presented within intellisense tool-tips as you type method-calls, which makes writing code much easier, quicker and less error prone.
Atomineer goes much further than any comparable extension - it keeps documentation and surrounding code tidy by enforcing line breaks, adjusting formatting and element ordering, indentation, punctuation and word wrapping - It works hard to keep comments tidy and readable on your behalf. All these options are configurable so it's easy to ensure all comments are in the precise style you require.
Teams using Atomineer often find that the extension actively promotes more consistent naming practices throughout the team, as good naming produces a better starting point for documentation.
It encourages developers to write documentation and keep it up to date. Programmers want to write code, and AtomineerUtils allows to focus on what they enjoy while still producing great docs.
In a similar way to unit tests, writing documentation encourages programmers to think more about their code and how it will be used by others. This generally leads to improved designs and lower defect rates in the associated code.
Typically an Atomineer developer saves around 1-2 working weeks per year just in the production of their documentation - a massive cost saving even before we factor in the less tangible down-stream time-saving and quality benefits.

Why choose Atomineer?

Atomineer Pro Documentation doesn't simply regurgitate the name of a code element with basic word re-ordering. It uses thousands of rules to try to generate the most meaningful possible documentation based on naming, types, context and existing documentation (e.g. within a class or its base classes).

Here are some examples of the comments that Atomineer will generate purely from the name and type of a parameter:

Parameter	Auto-generated documentation
char *serialIOBuff	[in,out] If non-null, buffer for serial i/o data.
string userInfo	Information describing the user.
IdGroup programIds	List of identifiers for the programs.
CString config_fname	Filename of the configuration file.
int processIndex	Zero-based index of the process.
params object[] fmtValues	A variable-length parameters list containing format values.

For more examples of classes, methods, parameters and return types see: Documentation XML format comments and Doxygen format comments.

...and Atomineer doesn't stop at documentation generation - it includes many special features to help you create and maintain documentation comments, such as duplicating existing documentation, providing live typing aids to speed up commenting, spell-checking to improve comment quality, word-wrapping and reformatting facilities to keep comments tidy, and a live preview window so you can read the documentation more easily.

Compare the features of Atomineer Pro Documentation with other extensions and you will see what incredible value for money it is. Then download the free trial to see for yourself how well it performs. And if it's missing something you need, email us and we'll do what we can to add support for you.