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:
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.
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'.
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.
Humans! AtomineerUtils provides many automatic (optional) formatting, word wrap and
punctuation facilities to make comments tidy and readable for humans too.