Atomineer Documentation Preprocessing & Conversion Rules

If you have existing documentation comments in a format that Atomineer can parse, you can configure Atomineer to read it and convert it to your new Atomineer style. This page describes several methods that can be used to facilitate comment conversions into the configured Atomineer format:

An 'alternate' comment style can be configured, to allow Atomineer to detect and convert comments in a form that does not match the new style it is generating.
Special Conversion Rules can be used to convert custom documentaiton entries into forms that Atomineer can recognise and process.
Pre-processing - You can write a Visual Studio Macro in Visual Studio that can read and process the comment text before Atomineer attempts to parse it. This gives you full control to convert any machine-parseable comment format into a form that Atomineer can convert. Example Macro code is supplied below, and in many cases very little work will be required to modify this code to suit your old comment style.
In addition, you can help Atomineer to parse bespoke typedefs and #define macros by applying Regular Expression replacements to the code that Atomineer as it parses.

Details of all these options are given below.

Converting documentation from a legacy format

Existing documentation can be converted if it is in a valid XmlDoc or Doxygen-like form, but encoded in an alternative format (Doxygen/Javadoc/Qt/Documentation XML) and style (block top/bottom separator lines and line prefixes) to the form that Atomineer generates. (If your comments are not in this form, you will need to use the 'preprocessing macro' approach described below to convert your legacy comment text into a close enough format that Atomineer can parse it - see below for details)

As this is a relatively rarely used option, it must be manually configured by opening the Atomineer Prefs.xml file (in your install folder, usually My Documents\Visual Studio 2008\Addins\AtomineerUtils) and adding the following elements to the <DocComment> section:

<Alt-Separator  value="/** " />
<Alt-LineHeader value=" * " />
<Alt-SeparatorB value=" */" />

You can set any text for the Separator (top line of the comment block), SeparatorB (bottom line of the comment block) and LineHeader (prefix for all lines within the block). If the separators and/or line prefix are not used, you must set value="(None)"

The comments can be read from Documentation XML, Doxygen, JavaDoc or Qt format, and will be converted into your configured 'primary' format (which may be any of those formats). If the format is the same, then it will simply be converted from an old block style to a new style). The standard tags (summary/brief, returns/return, seealso/sa etc) will be converted automatically as required, including embedded tags like c/see. Any custom tags used in your old format will simply be treated as embedded text appended to the previous entry, unless they match a custom entry tag that you have added to your comment Templates in rules.xml - if a matching template entry tag is found, the old comment data will be converted to the new documentation style and inserted into the final block as dictated by that template.

Custom <Conversion> Rules

In addition, Rules.xml contains a special section, <Conversions>, which tells Atomineer how to convert the entries it finds when converting legacy comments. This can:

Delete unwanted entries (e.g. delete '@ingroup' entirely)
Rename entries (e.g. '@description' to '<remarks>')

Note that at this time, the primary conversion process that is supported is Doxygen/JavaDoc/Qt to DocXML, simply because there has so far been no demand to convert DocXML the other way. However, basic conversions are already in place to convert from DocXml if required. Please email support@atomineerutils.com if you encounter any markup that is not converted well, and where possible we will try to upgrade Atomineer to support your conversion needs. (Also, the macro preprocessing approach described later on this page may help you to handle your conversion needs for yourself)

To convert between Doc Comment styles/formats, you may do any of the following:

To convert between different block format "skins", set the Alt-Separator, Alt-LineHeader and Alt-SeparatorB preferences in your Prefs.xml file so that Atomineer knows what the 'old' comment format looks like.
Set your Doxygen or DocXML Templates up to indicate the 'legal' entries in your new comment format, and how they should be ordered within the new comment block. Any entries that have the same tag in both old and new formats (e.g. param -> param) will be automatically 'converted' (reformatted in the new style). Any entries that are not considered 'legal' by Atomineer will be marked as 'deleted' with a ### prefix.

Common Doxygen/DocXml markup is automatically converted, e.g.:

\c ClassName         ->  <see cref="ClassName"/>
\code ... \endcode   ->  <code> ... </code>

Where an old entry should be removed entirely, add an entry like this within the <Conversions> section:
```
<ingroup convertTo=""/>            - delete all '\ingroup' entries
```

Where an old entry needs to be renamed, add an entry like this:

<author convertTo="programmer"/>   - convert all '<author>' entries to '@programmer'

A special pair of commands can be used to convert simple plain-text lists into a set of tags, e.g. To convert:

@references
			- \c MyClass
			- \c BaseClass

into a set of separate entries, you can use two forms:

<references convertEachLineTo="seealso cref" stripPrefix="-" /> will produce:		   
	<seealso cref='MyClass'/>
	<seealso cref='BaseClass'/>

<references convertEachLineTo="seealso" stripPrefix="- \c" /> will produce:
	<seealso>MyClass</seealso>
	<seealso>BaseClass</seealso>

If an 'incorrect' entry is converted (such as a param or exception entry that describes a parameter or exception that is not present in the code), the entry will be converted correctly, but then added at the bottom of the new comment with '###' prepended ('deleted' entry), just as would happen if you removed that param/exception and updated an existing comment. If unwanted, just execute the DocComment command a second time to clean away these 'deleted' entries.

Note that if the old comment format diverges too far from what Atomineer expects (such as using Doxygen aliases or custom Documentation XML elements not mentioned in the Conversions rules), the conversion may not work so well - you may need to 'tidy up' the comment (manually or perhaps using a Macro preprocessing script - see below) before applying the Atomineer conversion.

For example, the following Doxygen/JavaDoc comment uses the alternate format described by the prefs XML above, with JavaDoc-style entries:

/**
  * @brief  This is the brief description
  * @returns true if it feels like it
  * @param exampleParam An example parameter.
  * @date 15/04/2010
  * @author Jason
  */

...and it is converted to the following Documentation XML (in this case, using the default Atomineer format, with the entries rearranged in the order dictated by the default template):

////////////////////////////////////////////////////////////////////////////////////////////////////
/// <summary>   This is the brief description. </summary>
/// <author>    Jason. </author>
/// <date>      15/04/2010. </date>
///
/// <remarks>   Jason Williams, 16/04/2010. </remarks>
///
/// <param name="exampleParam"> An example parameter. </param>
///
/// <returns>   true if it feels like it. </returns>
////////////////////////////////////////////////////////////////////////////////////////////////////

Note that the author and date are recognised tags and thus preserved in the resulting comment - but if these are not set as 'legal' entries in your templates, they can be removed by simply executing ths DocComment command a second time to update the new comment. (Note also that the 'remarks' was not supplied, so a new auto-generated entry is added that records the author/date of the conversion). However, as you can see, Atomineer does the bulk of the conversion work for you.

Preprocessing Macros

Visual Studio provides a powerful built-in Visual Basic Macro system that provides excellent access to many of the internal functions of the IDE. These can be used to pre-process legacy documentation comments to convert them into a format that Atomineer can parse. Atomineer can then apply its formatting and layout rules to complete the task of converting the comments to the new format.

To enable this processing, you will need to first create a macro to be executed. Below is one to get you started. To install the macro, do the following:

In Visual Studio, go to Tools > Macros > Macros Explorer. A viewpane will appear in the Visual Studio window that shows your Macros (by default this may be empty or show 'RecordingProject' in the tree-view).

Right-click on the 'Macros' root entry, and choose New Macro Project. A dialog will appear.

Type a meaningful name for the Macro Project (we suggest 'Atomineer' and will assume this name below), and click Add. Your new project should now appear in the macro list, and fold open to show 'Module1'

Right click 'Module1' (in Atomineer) and choose Rename. Rename it to 'Custom' (you may use any name, but we will use this name in the example below)

Right-click 'Custom' (in Atomineer) and choose Edit. A new Visual Studio Macros window will appear.

Select-all in the macro code window containing the input focus, and paste in the macro code from here.
Finally, choose File > Close and Return

If you now select an entire legacy comment in a form that this macro can process, such as this:

/***********************************************************
* Usage:           Open the datafile for reading
* 
* Return Value:    true if the file was opened successfully
* 
* Notes:
*		Preconditions:
*			The filename must have been set in Init()
***********************************************************/

...and turn it into this:

/***********************************************************
* \brief            Open the datafile for reading 
* 
* \returns     true if the file was opened successfully 
* 
* \remarks 
*		Preconditions:
*			The filename must have been set in Init()
***********************************************************/

This is now in a form Atomineer can parse and convert to whatever form you have configured. If this does not match your block format, you will need to set up an Alternate format (see the top of this page) so that Atomineer can recognise this partially-converted comment. In this example, set the preference options to:

<Alt-Separator  value="/***********************************************************" />
<Alt-LineHeader value=" * " />
<Alt-SeparatorB value="***********************************************************/" />

You should now be able to convert the preprocessed comment by executing Add Doc Comment on the method. The last step is to tell Atomineer to execute the preprocessing macro for you. Edit the Preprocessing Rules (in the Atomineer preferences, go to Advanced Customisation and click the Preprocessing button) and uncomment the example entry:

<ConvertComment macro="Macros.Atomineer.Custom.ConvertExistingComment"/>

Now, when you execute Add Doc Comment, Atomineer should detect the legacy comment, select the entire comment block, execute your macro code to preprocess it, and then parse and update it to finish the conversion process.

It is recommended that when you have finished converting legacy comments, you disable the Preprocessing Rule so that Atomineer no longer tries to execute your macro - the mechanism that must be used involves selecting the comment (so it flickers terribly) and executing the macro slows down comment processing a bit.

Helping Atomineer to parse better

Occasionally, Atomineer hits something that confuses it, resulting in a lower quality of automatic documentation than expected. Typical examples are when a typedef or #define macro are used to represent special types in your code - Atomineer only parses the code near the location you wish to document, so it has no way of understanding what these special code symbols represent.

When parsing method declarations, Atomineer can apply optional regular-expression replacements to the text before it is parsed. This does not change the code in the document being processed, but just the view Atomineer has of it. This allows users to convert in-house types, typedefs and macros into a form that Atomineer can handle better.

To add regex replacements, edit the Preprocessing Rules (in the Atomineer preferences, go to Advanced Customisation and click the Preprocessing button) and add one or more entries like the examples that are provided:

<MethodDecl>
	<Replace pattern="OurTrueFalseType" replacement="bool" continue="true"/>
	<Replace pattern="OUR_TYPE\(bool\)" replacement="bool" continue="true"/>
</MethodDecl>

'pattern' and 'replacement' should be fairly self-explanatory, and the 'continue' attribute can be set to 'true' or 'false' to control whether or not any following Replace rules are executed if a rule causes the text to be altered.

Note: this replacement rule applies only to method/function/subroutine declarations. Please contact us if there are other code element types that you need a regex replacement mechanism added to.