|
| ||
AtomineerUtils FAQWhy use AtomineerUtils?Q: What is the benefit of using AtomineerUtils documentation? A: Auto-generated documentation confers a number of benefits:
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:
Purchase & Installation QuestionsQ: 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:
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 AtomineerUtilsQ: 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 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. | ||
| Copyright © 1996-2010 Atomineer. All Rights Reserved. Contact email address |