Question

I am using @remarks and @ingroup in my comment blocks but when I run Atomineer it keeps marking them for deletion and I’m not sure how to keep it from doing this. I looked at modifying rules in the .XML configuration files but I’m clearly missing something.

Example before processing with Atomineer:

//-------------------------------------------------------------------------------------
/// @copydoc interface_Result
///          
/// @ingroup platform_implementation module_core
//-------------------------------------------------------------------------------------

Example after processing with Atomineer:

//------------------------------------------------------------------------------------
/// @copydoc interface_Result.
///
/// ### ingroup platform_implementation module_core.
//------------------------------------------------------------------------------------

The documentation says: “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 AtomineerUtils will be marked as ‘deleted’ with a ### prefix.”

Any pointers or ideas would be appreciated? I really need it to quit doing this.

Thanks!

Answer 1

(I’m the author of Atomineer Pro Documentation)

In Visual Studio,

• Go to Tools > Atomineer > Atomineer Options…
• Switch to the “Advanced Customisation” tab
• Click the Block Templates – Doxygen button.

An editor (Notepad) will be opened containing the templates for you to customise.

The templates are XML-based, and they dictate to Atomineer:

• Which entries are legal (required or optional). Any entries not mentioned are considered “illegal” and deleted as you have found.
• The order in which entries should be sorted when comments are generated/updated
• Where to put additional whitespace (blank lines) in the comment blocks
• A few other things like whether punctuation correction should be enabled/disabled for each entry etc

There is a template for each different type of code element Atomineer can document, so you can get quite fine control of exactly how every part of your documentation looks, but it does mean you will have to copy and paste your new elements into each of the templates.

For example, here is the default template for a Doxygen method comment:

    <method>
        <prototype _punctuate="false" />
        <_ />
        <summary />
        <_ />
        <author _punctuate="false">%user%</author>
        <date _punctuate="false">%date%</date>
        <_ />
        <exception />
        <_ />
        <param />
        <_ />
        <returns />
        <_ />
        <sa _punctuate="false" _optional="true" />
    </method>

Each XML element (line) in this describes one entry in the comment. e.g. The XML tag <param/> corresponds to where the @param entries will be placed in the final comment block. The special element <_/> is used to indicate where blank lines should be inserted. (prototype is a special doxygen one, telling it where to insert the prototype/declaration @fn, @class, etc)

To allow @ingroup and @remarks to be inserted into Atomineer comments, just add entries for them in the positions you want it to appear in the comment, like this:

    <method>
        <prototype _punctuate="false" />
        <ingroup _optional="true" /> 
        <_ />
        <summary />
        <_ />
        <remarks _optional="true" />
        <_ />
        <author _punctuate="false">%user%</author>
        ...
    </method>

You will see that the example elements I’ve added have the attribute _optional="true" in them. Without this, Atomineer will add the entry to every comment (a required entry). If it is set to true, then the entry will not be added by Atomineer, but if you type it in yourself, Atomineer will make sure to preserve it when you update a doc-comment.

I apologise for how involved this is, but it’s a flexible system that allows everybody to get what they want, albeit sometimes requiring a few minutes of setting up. Whenever I get time I am writing improved configuration tools and tutorials to make this process easier. Once you’ve configured it, though, you should have many happy years ahead 😉

There is more documentation on Templates and the other things you can do in them here.

If you have further questions, feel free to drop a line to the support email, which is at the bottom of every page on the Atomineer website. I’m always happy to help.