AtomineerUtils FAQ

Why use AtomineerUtils?

Q: What is the benefit of using AtomineerUtils documentation?

A: Auto-generated documentation confers a number of benefits:

It minimises the effort involved in documenting methods. Although you often have to tweak and augment the auto-generated documentation, it's usually impressively close to what you need. This saves a lot of developer time (literally thousands of dollars worth a year) and encourages developers to document their code well, because it is almost effortless.
AtomineerUtils automatically keeps the documentation accurate as parameters, return values and thrown exceptions are changed in a method. This is the only realistic way of keeping documentation 100% in sync with the code.
Doc comments are picked up instantaneously by Visual Studio to give you the information in instant intellisense tool-tips as you type method-calls. This helps programmers work faster and make fewer mistakes as they have all the information they need at their fingertips.
It keeps documentation and surrounding code tidy by enforcing line breaks, formatting, element ordering, indentation, auto punctuation and word wrapping. All these options are highly configurable so it's easy to generate comments in the style you prefer.
Encourages higher quality code - A good descriptive name usually auto-generates 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.
Encourages developers to write documentation and keep it up to date. Programmers want to write code, not docs, so minimising the time and effort involved in documenting raises morale and improves the quality of documentation.
Pass Code Analysis. FXCop and similar CA tools will report warnings about poorly formed documentation or missing comments. AtomineerUtils makes it easy to ensure all the requisite XML elements are present to satisfy the CA rules.
AtomineerUtils can also reformat block comments to help keep code tidier and more maintainable in less time.

Q: I've used another add-in and it just causes poor documentation. Won't AtomineerUtils also do this?

A: Any add-in can only provide documentation based on the information available in the code - it will almost always be necessary for the programmer to augment the generated documentation. The point is that AtomineerUtils gets you 90% of the way there in an instant, which saves a lot of time and money. It's up to you to crack the whip over your programmers to get the last 10%! However, AtomineerUtils goes further than any other system to produce meaningful documentation as much as possible, to minimise the additional effort required to achieve a good description. Rather than using a generic algorithm to swap the ordering of the words and slap an 'of' in between, hundreds of rules, abbreviation expansions and special cases are used to derive sensible descriptions phrased in understandable English. Don't judge it on experience of any other add-ins - try it and you won't look back.

Q: What do others say about AtomineerUtils?

A: Here's a selection of typical comments about AtomineerUtils:

Terrific time saver - and it actually makes smart parameter comments!
The most advanced comment-generator utility I have ever seen
pretty impressive. Sometimes I am amazed by the quality of automatically generated documentation
Beautiful plugin
This is an impressive product; clearly, significant effort has been invested in its design and implementation.
Very nice tool for doxygen documentation of source code. Great work!!
Let me congratulate you for making an excellent add-in, it's being quite useful
Very cool utility
I am really impressed with it. It certainly seems highly configurable and produces very smart proposals
A fantastic tool
I like the AtomineerUtils very much. it is exactly, what we need to have our code documented in a very comfortable way
It's very good. Super work.
thank you for a nifty tool!
Your addin is really nice
[AtomineerUtils] has proven itself to be very useful
A very cool addin, super
...

Purchase & Installation Questions

Q: How do I upgrade my AtomineerUtils Pro - do I have to pay again?

A: Yes. Most companies charge hundreds of dollars for a year of updates on a product like this. I wanted to keep the licensing easy and low-cost for AtomineerUtils Pro, so it is just a simple micro-payment of $5 per download.

You can use the AtomineerUtils Pro that you bought for as long as you like. If you feel that the improvements since your version are worth another $5, just buy the latest version. Even if you upgrade every month, it's still great value for money.

Think of it this way:

Tools->AtomineerUtils->About... will tell you how many times you've used the commands. It's easy to clock up 250 uses a month.
Time how long it takes you to fill in the basics of a documentation comment for an average method manually (the comment block, names for the parameters, a thrown exception, and a return value, etc). AtomineerUtils easily saves at least 30-60 seconds every time you use it.
Factoring in all the running costs for a programmer in the USA, using AtomineerUtils easily equates to around $1000-$2000 saved a year. It'll pay back your $5 within 1 or 2 days.

Q: AtomineerUtils 'fails to load' when I run Visual Studio

A: Some companies map their 'My Documents' folder onto a network drive. Due to a .Net 'security feature', AtomineerUtils will fail to load if it is installed on a network drive ("The Add-in 'AtomineerUtils for Visual Studio' failed to load or caused an exception"). The solution is to install AtomineerUtils to a custom location on your own hard drive and then add that location manually to Visual Studio's Addins path. Just choose a new location in the installer, and it will tell you what to do next to complete the installation.

Using AtomineerUtils

Q: What are DocXml, Sandcastle and Doxygen?

A: DocXml (Xml Documentation) is a extensible standard defined by Microsoft. It is supported directly in the Visual Studio code editors, which will apply syntax colouring within documentation comments, and by Microsoft compilers and code analysis tools, which will issue warnings about poorly formed comments and uncommented parameters etc. Once you have compiled your code, Visual Studio Intellisense will use the summary/param/returns information to display useful tooltips above function and class names as you type them in your code. Finally, the XML is exported by the compiler for use in external tools (e.g. Sandcastle, Doxygen) to produce quality external documentation. See the MSDN section on Xml Documentation for more details.

A: Sandcastle is a free tool, created by Microsoft, for generating external documentation from the XML comments in Visual Studio solutions. See here for full details.

A: Doxygen is one of the most popular external documentation tools available. See here for full details and a free download. As well as supporting the DocXml format, it supports a variety of other popular formats, several of which are supported by AtomineerUtils.

Q: Will AtomineerUtils convert my existing comments to its format?

A: Existing XMLDoc comments in the standard Microsoft 'Triple slash' format will be parsed and converted, as will any comments that match the format that AtomineerUtils is configured to generate. However, note that AtomineerUtils will attempt to preserve as much of the format (such as blank lines) in these imported comments as it can, and may get confused by non-atomineer-like layouts, so you may need to do a bit of manual cleaning up afterwards.

Q: I have found a code element that AtomineerUtils gives odd auto-documentation for. What can I do?

A: Edit rules.xml to handle the name exactly as you wish. If you email me the definition for the code element you are trying to comment, or your additions to rules.xml, I'll try to improve AtomineerUtils' default handling. Because AtomineerUtils uses an in-built parser that has to cope with C/C++/C#/Java (indeed, any sufficiently C-like language such as Maya's MEL script), it can sometimes get confused by syntaxes or custom macros that I have not encountered in my travels.

Q: I don't like the style/layout of the AtomineerUtils comments
Q: I don't want blank lines or extra whitespace in my comments
Q: I don't want the top and bottom separator lines in my comments

A: This is all highly configurable (in AtomineerUtils Pro). You can change most formatting options in your preferences (e.g. no separators) - this will be previewed at the bottom of the window so you can see what effect it will have. Other more involved options (e.g. controlling word wrap for individual entries in the doc comment) may require you to edit the <Templates> section in Rules.xml. If you can't achieve the comment format you desire, drop me an email with an example of what you want and I'll try to help. I haven't turned anyone away empty-handed yet!

Q: Is it possible to test changes to 'rules.xml' without restarting?

A: Yes - AtomineerUtils detects any changes to rules.xml or prefs.xml and automatically reloads the rules/preferences the next time you execute the Add Doc Comment command. There is no need to restart Visual Studio to pick up the changes.

Q: I don't want auto-doc text to be inserted unless it provides a useful description

A: Sometimes this can save typing, sometimes it just gets in the way. If you don't like it, delete the 'catch-all' (the final <Set> element just before the </Parameters> end tag) in the rules.xml. Indeed, you can delete/alter any or all of the rules from the appropriate section to change any auto-doc behaviour that you disagree with.

Q: I want abbreviation 'doc' to be expanded to 'delete on close' instead of 'document'. Can I do this?

A: Just edit the abbreviations list at the bottom of Rules.xml. Be careful about adding abbreviations that might have two or more meanings though (e.g. 'app' might be your abbreviation for 'application' or 'append'), as AtomineerUtils can only use one.

Q: Can I add literal text in atomineer comments - e.g. a default TODO item that appears in the VS Task List to remind my developers to fill the fields in?

A: Yes, this is easily accomplished in Rules.xml. Just edit the template and enter the literal text that you wish to insert in the appropriate element. Note that VS only picks up the TODO if it is on its own line (not prefixed by an XML element), so you must enter the "TODO" on a new line in Rules.xml.

Q: Can I use AtomineerUtils for a language other than English?

A: Yes. The only English-specific rules in AtomineerUtils are the 'Pluralise' command and 'a/an/the' handling. The rest of the handling is entirely user-editable in the Rules.xml file - it just needs translation to the language you desire. If you do create a localised version of rules.xml, please consider sending it to me so I can publish it here for others to use.

Q: Why doesn't AtomineerUtils insert DocXml 'markup' around parameter names, etc?

A: The AtomineerUtils philosophy is (primarily) to produce human-readable comments in the code, in a format that can (secondarily) be picked up by external documentation tools. Adding loads of extra XML tags within the documentation makes it really unreadable (IMHO) while often not conferring any real benefit when used in offline help (I can't remember the last time I hyperlinked to a parameter in a method's documentation - because I have never needed to do it).

However, these tags can trivially be added into the Rules.xml (albeit they may be required in many different rules). A planned future feature is to add such tags and use a preference option to control whether or not they are emitted to the generated comment.