AtomineerUtils Pro Configurability Examples
AtomineerUtils Pro's comment format is highly configurable, within the constraints of what makes up a
legal DocXml or Doxygen comment. Note that the free version (AtomineerUtils) does not support some of these
customisation options (specifically top/bottom separators, line headers, removal of blank lines, and the
JAVADOC_AUTOBRIEF style for Doxygen comments).
The most common options can be set in the AtomineerUtils Options,
but considerable additional control can be exercised through the Rules.xml file. (Rules.xml is
well commented with documentation on how to achieve this. You will find this file in the
installation folder you selected in the installer - run the installer again to see where this was)
This page includes a number of examples, showing just a few of the variations possible for both DocXml
and Doxygen comments
DocXml
////////////////////////////////////////////////////////////////////////////////////////////////////
/// <summary> Tests skins. </summary>
///
/// <remarks> Jason Williams, 23/04/2009. </remarks>
///
/// <param name="exampleParam"> The example parameter. </param>
///
/// <returns> true if the test passes, false if the test fails. </returns>
//////////////////////////////////////////////////////////////////////////////////////////////////// |
Default DocXml style |
/// <summary> Tests skins. </summary>
/// <remarks> Jason Williams, 23/04/2009. </remarks>
/// <param name="exampleParam"> The example parameter. </param>
/// <returns> true if the test passes, false if the test fails. </returns> |
Compact, no top/bottom separators |
////////////////////////////////////////////////////////////////////////////////////////////////////
///<summary>Tests skins</summary>
///
///<remarks>Jason Williams, 23/04/2009</remarks>
///
///<param name="exampleParam">The example parameter</param>
///
///<returns>true if the test passes, false if the test fails</returns>
//////////////////////////////////////////////////////////////////////////////////////////////////// |
With no padding or punctuation correction. |
///------------------------------------------------------------------------------
/// <summary> Tests skins. </summary>
///
/// <remarks> Jason Williams, 23/04/2009. </remarks>
///
/// <param name="exampleParam"> The example parameter. </param>
///
/// <returns> true if the test passes, false if the test fails. </returns>
///------------------------------------------------------------------------------ |
User defined top/bottom separators |
/********************************************************************************/
/// <summary> Tests skins. </summary>
///
/// <remarks> Jason Williams, 23/04/2009. </remarks>
///
/// <param name="exampleParam"> The example parameter. </param>
///
/// <returns> true if the test passes, false if the test fails. </returns>
/********************************************************************************/ |
User defined top/bottom separators |
/**=================================================================================================
Method: TestSkins
=================================================================================================
<summary> Tests skins. </summary>
<remarks> Jason Williams, 28/10/2009. </remarks>
<param name="exampleParam"> The example parameter. </param>
<returns> true if the test passes, false if the test fails. </returns>
-----------------------------------------------------------------------------------------------*/ |
User-defined 3-line header, using
%type% and %name% to describe the code element. |
/**
<summary> Tests skins. </summary>
<remarks> Jason Williams, 23/04/2009. </remarks>
<param name="exampleParam"> The example parameter. </param>
<returns> true if the test passes, false if the test fails. </returns>
**/ |
User defined top/bottom separators, whitespace for line headers |
//===============================================================================
/**
<summary> Tests skins. </summary>
<remarks> Jason Williams, 23/04/2009. </remarks>
<param name="exampleParam"> The example parameter. </param>
<returns> true if the test passes, false if the test fails. </returns>
*/
//------------------------------------------------------------------------------- |
User defined multi-line top/bottom separators, whitespace for line headers |
/**
* <summary> Tests skins. </summary>
*
* <remarks> Jason Williams, 23/04/2009. </remarks>
*
* <param name="exampleParam"> The example parameter. </param>
*
* <returns> true if the test passes, false if the test fails. </returns>
*****************************************************************************/ |
User defined top/bottom separators and line headers |
#if false
<summary> Tests skins. </summary>
<remarks> Jason Williams, 23/04/2009. </remarks>
<param name="exampleParam"> The example parameter. </param>
<returns> true if the test passes, false if the test fails. </returns>
#endif |
User defined top/bottom separators, no line headers |
////////////////////////////////////////////////////////////////////////////////////////////////////
/// <param name="exampleParam"> The example parameter. </param>
///
/// <returns> true if the test passes, false if the test fails. </returns>
///
/// <summary> Tests skins. </summary>
//////////////////////////////////////////////////////////////////////////////////////////////////// |
Custom element ordering, remarks removed |
...
/// <remarks> Created: 1:34pm, 23 April 2009 by Jason Williams on JasonW-PC01. </remarks>
... |
Custom text (and variable expansion) in remarks element... |
...
/// <author> Jason Williams </author>
/// <date> 23/04/2009 </date>
... |
...or replace it entirely with custom elements. |
/// <remarks>
/// TODO: Fill in the remarks
/// </remarks> |
Use of default TODO tags to remind developers to complete the comment. (Compatible with Visual Studio's Task List window). |
DocXml BlockFormat examples
The block formatting preferences control how each entry is formatted within DocXml comment structures.
In all cases the block of entry text is indented to line up with the first word of the entry.
////////////////////////////////////////////////////////////////////////////////////////////////////
/// <summary> A single-line entry formats like this. </summary>
///
/// <summary> If an entry covers multiple lines, AtomineerUtils will format the
/// contained text just like this. </summary>
//////////////////////////////////////////////////////////////////////////////////////////////////// |
"Put <tags> on the same lines as the entry text"
(Flow). |
////////////////////////////////////////////////////////////////////////////////////////////////////
/// <summary>
/// A single-line entry formats like this.
/// </summary>
///
/// <summary>
/// If an entry covers multiple lines, AtomineerUtils will format the contained text
/// just like this.
/// </summary>
//////////////////////////////////////////////////////////////////////////////////////////////////// |
"Put <tags> on separate lines & left align text".
(FrameFlush) |
////////////////////////////////////////////////////////////////////////////////////////////////////
/// <summary> A single-line entry formats like this. </summary>
///
/// <summary>
/// If an entry covers multiple lines, AtomineerUtils will format the contained text
/// just like this.
/// </summary>
//////////////////////////////////////////////////////////////////////////////////////////////////// |
"Put <tags> on separate lines & left align text, unless it fits in a single line".
(FrameFlushFlowSingle) |
////////////////////////////////////////////////////////////////////////////////////////////////////
/// <summary>
/// A single-line entry formats like this.
/// </summary>
///
/// <summary>
/// If an entry covers multiple lines, AtomineerUtils will format the contained
/// text just like this.
/// </summary>
//////////////////////////////////////////////////////////////////////////////////////////////////// |
"Put <tags> on separate lines & indent entry text"
(FrameIndent) |
////////////////////////////////////////////////////////////////////////////////////////////////////
/// <summary> A single-line entry formats like this. </summary>
///
/// <summary>
/// If an entry covers multiple lines, AtomineerUtils will format the contained
/// text just like this.
/// </summary>
//////////////////////////////////////////////////////////////////////////////////////////////////// |
"Put <tags> on separate lines & indent text, unless it fits in a single line"
(FrameIndentFlowSingle) |
File Headers
DocXml doesn't directly support file headers. For this reason, AtomineerUtils supports both XML-based
and plain-text file header comments. Both styles are configurable within the rules.xml file, and can
be populated using variables such as %user% and %filename% to fill in context-specific details.
Below are some examples:
////////////////////////////////////////////////////////////////////////////////////////////////////
// file: AtomineerUtils\CustomerBookingDlg.cs
//
// summary: Implements the customer booking Dialog
//////////////////////////////////////////////////////////////////////////////////////////////////// |
Default AtomineerUtils file header
(plain text) |
////////////////////////////////////////////////////////////////////////////////////////////////////
// project: Flight Booking System
// file: AtomineerUtils\CustomerBookingDlg.cs
//
// summary: Implements the customer booking Dialog
//
// Copyright (c) 2009 atomineer.com. All rights reserved.
//
// Date Developer Change
// 13/06/2009 Jason Williams Created
//////////////////////////////////////////////////////////////////////////////////////////////////// |
More comprehensive plain-text example |
////////////////////////////////////////////////////////////////////////////////////////////////////
/// <file> AtomineerUtils\CustomerBookingDlg.cs. </file>
///
/// <summary> Implements the customer booking Dialog. </summary>
//////////////////////////////////////////////////////////////////////////////////////////////////// |
XML equivalent of the default file header. |
Doxygen
Doxygen format is just as configurable as DocXml, so many of the above examples can be achieved while
using Doxygen markup. There are also some Doxygen-specific options. Some examples are:
////////////////////////////////////////////////////////////////////////////////////////////////////
/// \fn bool SkinTest(int exampleParam)
///
/// \brief Tests skins.
///
/// \author Jason Williams
/// \date 23/04/2009
///
/// \param exampleParam The example parameter.
///
/// \return true if the test passes, false if the test fails.
//////////////////////////////////////////////////////////////////////////////////////////////////// |
Default Doxygen style |
////////////////////////////////////////////////////////////////////////////////////////////////////
/// @fn bool SkinTest(int exampleParam)
///
/// @brief Tests skins.
///
/// @author Jason Williams
/// @date 23/04/2009
///
/// @param exampleParam The example parameter.
///
/// @return true if the test passes, false if the test fails.
//////////////////////////////////////////////////////////////////////////////////////////////////// |
Alternate Doxygen style
(@ command prefix) |
////////////////////////////////////////////////////////////////////////////////////////////////////
/// \brief Tests skins.
///
/// \author Jason Williams
/// \date 23/04/2009
///
/// \param exampleParam The example parameter.
///
/// \return true if the test passes, false if the test fails.
//////////////////////////////////////////////////////////////////////////////////////////////////// |
No function prototype |
/**
* Tests skins.
*
* \author Jason Williams
* \date 23/04/2009
*
* \param exampleParam The example parameter.
*
* \return true if the test passes, false if the test fails.
*/ |
JAVADOC_AUTOBRIEF style (no tag on the 'brief' entry), within a block comment |
/**
\fn bool SkinTest(int exampleParam)
\brief Tests skins.
\author Jason Williams
\date 23/04/2009
\param exampleParam The example parameter.
\return true if the test passes, false if the test fails.
*/ |
Block comment style |
/// \fn bool SkinTest(int exampleParam)
/// \brief Tests skins.
/// \author Jason Williams
/// \date 23/04/2009
/// \param exampleParam The example parameter.
/// \return true if the test passes, false if the test fails. |
Compact style |
|
