AtomineerUtils Add-in for Visual Studio 2010, 2008 & 2005

AtomineerUtils Pro Documentation for Visual Studio provides unsurpassed code documentation (Documentation XML, Doxygen, Qt and JavaDoc format) comment generation, updating and conversions, as well as several handy outlining, code generation and clipboard commands.

AtomineerUtils supports C#, Visual Basic, C++/CLI, C++, C and Java code

• Save time - save effort - save money.
• Eliminate almost all 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 documentaion.
• Convert and update legacy documentation into a new standard.

Features - Document code better faster tidier cheaper

With a single keypress or menu command, the add-in can:

• Create or update highly configurable Documentation XML, Doxygen, Qt or JavaDoc-format documentation comments for code elements (file, namespace, class, interface, struct, enum, variable, property, event, delegate and function) in your code. This includes advanced support for automatically documenting all parameters, generic type parameters, thrown exceptions and return codes, automatically making use of existing documentation from related base class and override methods/properties and existing parameters within the same class, and generating accurate and specialised documentation for hundreds 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 - what's so special about it?

For teams of developers to work on a product, they need to efficiently transfer information about their classes and methods to each other. Even a lone programmer will usually forget the finer details of his code after a few weeks. When you're writing code that calls a method, you don't want to waste time jumping to its source code to work out what it does and how to call it. Documentation comments allow you to see that information as an intellisense tool-tip display as you type - the purpose/usage of the method and details of the parameters and return value. This significantly improves productivity and reduces errors.

Many programmers advocate 'self documenting' code, where clear and descriptive naming conventions make it easier to understand code quickly. Documentation takes this concept a step further by presenting that information in easily understood English rather than sometimes rather confusing 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 merely the first and most basic step of writing well documented, maintainable code.

In addition, there are many tools such as Doxygen (all languages) and SandCastle or NDoc (.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
• Even dedicated documentors will find their comments often get 'out of sync' with the code

AtomineerUtils auto-generated documentation confers a number of benefits:

• It provides the raw block skeleton instantly, in a standardised (but user-configurable) format
• It minimises the effort involved in documenting. A high proportion of documentation content is repetitive and easily filled in by the computer rather than the developer. Although you sometimes have to tweak and augment the comments AtomineerUtils provides, it's usually impressively close to what you need, thanks to AtomineerUtils' advanced heuristic approach. This saves a lot of developer time and encourages developers to document their code well, because it is so nearly effortless to achieve excellent results.
• AtomineerUtils pulls together information about a code element from many different sources and presents it to programmers in a standardised form. This brings the information you need to your fingertips in a quick to read format - exceptions thrown within methods, information about interface implementations, consistent documentation on parameters across a class, etc. Writing 'self documenting' code is a great start, but does not make this wealth of information easy to find.
• AtomineerUtils automatically keeps the documentation accurate when parameters, return values and thrown exceptions are changed in a method, or get/set accessors are added to a property. It automatically ensures that your XML/HTML is valid. This is the only realistic way of keeping documentation 100% in sync with the code and compatible with intellisense and external tools.
• In many languages, XML Documentation comments are picked up instantaneously 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.
• It keeps documentation and surrounding code tidy by enforcing line breaks, adjusting formatting, element ordering, indentation, punctuation and word wrapping - AtomineerUtils works hard to keep comments tidy and readable on your behalf. All these options are highly configurable so it's easy to ensure all comments are in the precise style you require.
• It encourages higher quality code - Good descriptive names usually auto-generate most of the documentation comment for you, while poor names leave you with more work to complete the documentation, so AtomineerUtils actively encourages a better coding style.
• It encourages developers to write documentation and keep it up to date. Programmers want to write source code, so minimising the time and effort involved in documenting raises morale and improves the quality of documentation.
• AtomineerUtils saves huge amounts of time (documenting code, understanding code, and writing and using maintainable code) - and time is money. A typical programmer uses AtomineerUtils around 100-200 times every day.

Put simply, AtomineerUtils raises developer morale, increases code quality, and typically saves thousands of dollars per developer per year.

What makes AtomineerUtils Documentation so special?

AtomineerUtils doesn't simply regurgitate the name of a code element with a simple word re-ordering. It tries to generate meaningful documentation based on naming, types, context and existing documentation. Here are some examples of the comments that AtomineerUtils will generate purely from the name and type of a parameter:

And so on... AtomineerUtils will often generate even better documentation when it recognises the context of the item it is documenting (the method name, its signature and attributes, overloads and overrides, and even similar parameters that have already been documented elsewhere in a class). For example, if a method is 'float CalcRecip()', AtomineerUtils documents the return type as 'The calculated reciprocal' rather than anything unhelpful like 'a float'.

To illustrate how AtomineerUtils provides unsurpassed code documentation facilities, a comparison of similar products is available here.

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

Compatibility

The add-ins are compatible with Visual Studio (Standard, Professional, Premium, Ultimate and Team System) 2010, 2008, and 2005 (32/64 bit WinXP, Vista, and Win7). They are not compatible with Visual Studio Express Editions which unfortunately do not support Add-ins. The commands can be used by developers working with C#, C++/CLI, C++, C, Java and Visual Basic code, with specific support for common (.Net, MFC, STL and K&R) coding and naming conventions.

AtomineerUtils understands how to document files, namespaces, classes, interfaces, structs, functions/methods/subroutines, constructors, destructors, finalizers, properties, indexers, operators, delegates, events, C++ macros, enumerated types, typedefs, variables, generics, templates, return types, parameters, type-parameters, and thrown exceptions.

The documentation comments are compatible with the following systems:

• Documentation XML (DocXml) format as supported by Visual Studio, Intellisense, and the SandCastle documentation builder.
• Doxygen, Qt and JavaDoc formats.
• Humans! AtomineerUtils provides many automatic (optional) formatting, word wrap and punctuation facilities to make comments tidy and readable for humans too.