Why use Atomineer Pro Documentation?

Q: What is the benefit of using Atomineer 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 Atomineer 100 times a day, 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")
Atomineer 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 Atomineer 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. Atomineer makes it easy to ensure all the requisite XML elements are present to satisfy the CA rules.
Atomineer 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 Atomineer 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, Atomineer 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 Atomineer 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 Atomineer 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 Atomineer Pro Documentation.

Installation Questions

Q: Atomineer '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', Atomineer may fail to load if it is installed on a network drive ("The Add-in 'Atomineer Pro Documentation' failed to load or caused an exception"). The solution is to install Atomineer 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.

Q: Atomineer doesn't appear in the Visual Studio Tools Menu

A:First, please be aware that Express Editions of Visual Studio do not allow addins to be used. Atomineer can therefore only be used in Standard, Professional, Premium or Ultimate (and historically, Team System) editions.

For the editions that support addins, sometimes Visual Studio is configured not to allow add-ins to start up, or it fails to search in the right folder to find Atomineer. This is easily corrected as follows:

Run Visual Studio and go to Tools > Options, Addin/Macros security.

Make sure the second check-box (Allow add-in components to load) is ticked.

Check that the list of Add-in file paths includes the folder Atomineer was installed into. By default Atomineer is installed to a 'built-in' path, but if the set-up of your Visual Studio is missing the required path for any reason, this could be the problem. Click the Add... button and browse to the install path (Run the Atomineer installer if you need a reminder of its location). Inside is a Visual Studio 2010\Addins folder that you must add to the search paths in Visual Studio.

If either of these are the problem, then after restarting Visual Studio, Atomineer should appear in your Tools menu. If it still doesn't show up, then go to Tools > Add in Manager. If the addin has been found, it will be listed here. It will have three check-boxes for the addin. To ensure that it is loaded, make sure the first (on the addin name) and the second (in the "Startup" column) are ticked.

It's almost certain that one of these things will be the problem - but please let us know if you still can't get the add-in to load and we'll be happy to help you investigate further.

Q: Atomineer reports errors about failing to load assembly 'stdole' on startup.

A: If you are using a partial install of Visual Studio (e.g. C++ support only), a C# dll required for add-ins to operate may be missing. An easy solution is to use the Visual Studio installer to add the Visual C# Tools. An alternative is to install stdole into your GAC with a command line like the following (it will need administrator privileges):

"C:\Program Files (x86)\Microsoft SDKs\Windows\v7.0A\Bin\gacutil.exe"
    -i "C:\Program Files (x86)\Common Files\microsoft shared\MSEnv\PublicAssemblies\stdole.dll"

Using Atomineer Pro Documentation

Q: Does Atomineer generate CHM, HTML, or PDF files?

A: No, Atomineer 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 Atomineer.

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 Atomineer convert my existing comments to its format?

A: Yes!

Existing XML Documentation comments in any of the formats supported by Atomineer (XML, Doxygen, Qt, JavaDoc) will be automatically parsed and converted into whichever format you have configured in Atomineer. 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, Atomineer 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 Atomineer-supported format. Atomineer 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 Atomineer. Full details on this conversion process can be found here.

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

A: For any individual case you can of course just undo or 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 Atomineer's default handling.

Atomineer 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 Atomineer to handle it perfectly.

Q: I don't like the style/layout of the Atomineer 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.

Due to the extensive configurability of Atomineer, it can be difficult to work out how to achieve the results you require. If you'd like some help configuring Atomineer to suit your needs, please just contact us for free assistance., enclosing example(s) of the comments you wish to produce, and we will reply with instructions on how to achieve them (or get as close as possible within the restrictions imposed by the Xml Documentation, JavaDoc, Qt or Doxygen documentation formats).

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

A: Yes - Atomineer detects any changes to rules or preferences and automatically reloads them the next time you execute any Atomineer 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 an abbreviation to be expanded to a different word. 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 Atomineer 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 Atomineer for a language other than English?

A: Yes. The only English-specific rules in Atomineer 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 Atomineer community.

Q: Why doesn't Atomineer insert Xml 'markup' around parameter names, etc?

A: The Atomineer 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 is often superfluous, unless a method has a huge amount of documentation), which is why Atomineer does not add these tags by default.

However, any text you enter into your comments will be preserved by Atomineer when it updates your comments, and this includes xml/html element tags.