Atomineer Pro Documentation for
Visual Studio
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.
-
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
documentation.
-
Accelerate editing of comments with formatting, word wrapping and
bullet-list typing aids.
|
Features in Detail - -
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, 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.
MaMany 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?li>
- 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.
InIn 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 addin 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. |