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 - a typical developer uses AtomineerUtils 100 times a day, each time saving seconds to minutes every time)
It encourages developers to document their code well, because it is almost effortless. ("even people reluctant to use it have shown promising enthusiasm once they installed the tool")
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 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 regular code-comments to help keep code tidier and more maintainable in less time.

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

A: Most add-ins do little more than insert basic predefined text snippets into your code. The only other add-in we know of that does significantly more than this (true context-sensitive documentation) is GhostDoc. However, AtomineerUtils takes automatic-documentation generation to a whole new level (using thousands of rules rather than tens of rules, to generate significantly better documentation in much wider range of cases). Nevertheless, 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 provides the bulk of the comment in an instant, which saves a lot of time and money when you consider that a typical programmer will use it over 100 times every day. It's up to you to crack the whip over your programmers to get the last 5% to achieve excellent documentation! Don't judge AtomineerUtils on your experience of any other add-ins - just try the free trial for 5 minutes and you'll see why so many developers are switching to AtomineerUtils.

Installation Questions

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 2.0 'security feature' (fixed in Windows 7 and .net 3.5 SP1), AtomineerUtils may 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: Does AtomineerUtils generate CHM, HTML, or PDF files?

A: No, AtomineerUtils creates and updates comment blocks within your source code. These can then be 'harvested' by other programs (the built in Visual Studio Intellisense system, and external tools like SandCastle, Doxygen, and JavaDoc - see the next question for more information on these) to create external documentation in various formats.

Q: What are DocXml, Sandcastle, Doxygen, Qt and JavaDoc?

A: DocXml (Xml Documentation) is an 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 (variations on Doxygen and JavaDoc) are supported by AtomineerUtils.

A: Qt is a documentation standard defined by Nokia for their Qt development system. See here for some details. This format is very similar to the Doxygen and JavaDoc formats (it's one of the formats Doxygen supports, using commands prefixed by '/'), and is often called 'Doxygen format' because Doxygen provides such excellent support for Qt and many variations of comment style that are similar to it.

A: JavaDoc is a documentation standard designed for Java code. See here for full details. This format is very similar to the Doxygen and Qt formats (it's one of the formats Doxygen supports, where commands are prefixed by '@'), and is often called 'Doxygen format' because Doxygen provides such excellent support for JavaDoc and many variations of comment style that are similar to it.

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

A: Yes!

Existing XML Documentation comments in any of the formats supported by AtomineerUtils (XML, Doxygen, Qt, JavaDoc) will be automatically parsed and converted into whichever format you have configured in AtomineerUtils. A number of conversion and preprocessing configuration options are supplied to allow a lot of control over the conversion process.

In cases where legacy documentation doesn't match the supported formats, AtomineerUtils is not able to directly parse the old comments. However, in this case, it can locate the comment block and then execute a user-defined Visual Studio Macro (VBScript) on it, allowing you to write a small bit of code that will convert your comment text into something similar to any AtomineerUtils-supported format. AtomineerUtils can then complete the conversion process and tidy up the results for you. An example macro and instructions are supplied, so with a small amount of tweaking it is usually fairly easy to convert almost any documentation comment format into one of the formats supported by AtomineerUtils. Full details on this conversion process can be found here.

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

A: For any individual case you can of course just edit the generated text. In cases where unwanted documentation is generated repeatedly, you can edit your custom rules to generate the documentation you require automatically, or to stop that documentation being generated entirely. If you email us the definition for the code element you are trying to comment, or your additions to the rules, we'll try to improve AtomineerUtils' default handling.

AtomineerUtils uses an in-built parser that handles isolated snippets of C/C++/C#/Java/VB code, so it can sometimes be confused by naming/coding conventions that it has not encountered before. Just send us an example of any code that it handles incorrectly and we'll do our best to update AtomineerUtils to handle it perfectly.

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. 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, send us an email with an example of what you want and we'll try to help. In almost every case we have encountered we have been able to achieve the format that customers have asked for.

Q: Is it possible to test changes to my Rules without restarting?

A: Yes - AtomineerUtils detects any changes to rules or preferences and automatically reloads them the next time you execute any AtomineerUtils 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 auto-doc 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 appropriate section of the Rules. Indeed, you can delete/alter any or all of the rules from the appropriate section to change any auto-doc behaviour that you don't like.

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 in the rules. 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 the Rules. 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 the rules.

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 - it just needs translation to the language you desire. If you do create a localised version of the rules, please consider sending it to us so we can share it with the AtomineerUtils community.

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 many extra XML tags within the documentation makes it much less readable while often not conferring any real benefit when used in offline help (e.g. a hyperlink between summary text and one of the parameters on the same page are often superfluous, unless a method has a huge amount of documentation). However, these tags can trivially be added into the Rules should they be required.