AtomineerUtils Pro Configurability Examples

AtomineerUtils Pro's code documentation comment format is highly configurable, within the constraints of what makes up a legal Documentation Xml, Doxygen, Qt or JavaDoc comment.

The most common options can be set in the AtomineerUtils Options, but considerable additional control can be exercised through the customisable Rules and Templates.

This page includes a number of examples, showing just a few of the variations possible for the supported documentation comment formats.

Documentation Xml

The default AtomineerUtils 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>
  ////////////////////////////////////////////////////////////////////////////////////////////////////

A compact style with no top/bottom separators or blank lines


  /// <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>

A Visual Basic compatible 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>
  '''-------------------------------------------------------------------------------------------------

Default style with entry padding and punctuation correction disabled.


  ////////////////////////////////////////////////////////////////////////////////////////////////////
  ///<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 separator lines


  ///------------------------------------------------------------------------------
  /// <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 separator lines


  /********************************************************************************/
  /// <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 3-line separator lines, using %type% and %name% to describe the code element in the top separator section. Lines are not prefixed.


  /**=================================================================================================
     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 top/bottom separators, no line prefixes


  /**
      <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, no line prefixes


  //============================== Corporation XYZ ================================
  /**
      <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 prefixes


  /**
    * <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, no line prefixes


  #region Header
  /**
  <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>
  **/
  #endregion

They don't even need to be comments as long as you can get the compiler to ignore them!


  #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

Custom element ordering, remarks removed


  ////////////////////////////////////////////////////////////////////////////////////////////////////
  /// <param name="exampleParam"> The example parameter. </param>
  ///
  /// <returns> true if the test passes, false if the test fails. </returns>
  ///
  /// <summary> Tests skins. </summary>
  ////////////////////////////////////////////////////////////////////////////////////////////////////

Custom text (and variable expansion) in remarks element...
... /// <remarks> Created: 1:34pm, 23 April 2009 by Jason Williams on JasonW-PC01. </remarks> ...

...remarks section replaced entirely with custom XML elements for author/date.
... /// <author> Jason Williams </author> /// <date> 23/04/2009 </date> ...

Automatic insertion of default TODO tags to remind developers to complete the comment. (Compatible with Visual Studio's Task List window).
/// <remarks> /// TODO: Fill in the remarks /// </remarks>

Entry Formatting examples

The entry formatting preferences control how each entry is formatted within the comment structures. Similar settings are available for Doxygen/Qt/JavaDoc comments. The examples below show just a few of the hundreds of formatting styles that can be achieved.

Symmetrical Tags, Indented Text


  ////////////////////////////////////////////////////////////////////////////////////////////////////
  /// <summary>
  ///     This example illustrates how documentation entries can be auto-formatted by
  ///     AtomineerUtils. The formatting options allow you to choose an ideal compromise between
  ///     readability and compactness.
  /// </summary>
  ////////////////////////////////////////////////////////////////////////////////////////////////////

Symmetrical Tags, Left-Aligned Text


  ////////////////////////////////////////////////////////////////////////////////////////////////////
  /// <summary>
  /// This example illustrates how documentation entries can be auto-formatted by AtomineerUtils. The
  /// formatting options allow you to choose an ideal compromise between readability and compactness.
  /// </summary>
  ////////////////////////////////////////////////////////////////////////////////////////////////////

Tabular Text (inline end tag)


  ////////////////////////////////////////////////////////////////////////////////////////////////////
  /// <summary> This example illustrates how documentation entries can be auto-formatted by
  ///           AtomineerUtils. The formatting options allow you to choose an ideal compromise
  ///           between readability and compactness. </summary>
  ////////////////////////////////////////////////////////////////////////////////////////////////////

Flowing, indented text


  ////////////////////////////////////////////////////////////////////////////////////////////////////
  /// <summary> This example illustrates how documentation entries can be auto-formatted by
  ///    AtomineerUtils. The formatting options allow you to choose an ideal compromise between
  ///    readability and compactness. </summary>
  ////////////////////////////////////////////////////////////////////////////////////////////////////

Flowing, left-aligned text


  ////////////////////////////////////////////////////////////////////////////////////////////////////
  /// <summary> This example illustrates how documentation entries can be auto-formatted by
  /// AtomineerUtils. The formatting options allow you to choose an ideal compromise between
  /// readability and compactness. </summary>
  ////////////////////////////////////////////////////////////////////////////////////////////////////

Tabular text (end tag on new line)


  ////////////////////////////////////////////////////////////////////////////////////////////////////
  /// <summary> This example illustrates how documentation entries can be auto-formatted by
  ///           AtomineerUtils. The formatting options allow you to choose an ideal compromise
  ///           between readability and compactness.
  ///           </summary>
  ////////////////////////////////////////////////////////////////////////////////////////////////////

Flowing, indented text (end tag on new line)


  ////////////////////////////////////////////////////////////////////////////////////////////////////
  /// <summary> This example illustrates how documentation entries can be auto-formatted by
  ///    AtomineerUtils. The formatting options allow you to choose an ideal compromise between 
  ///    readability and compactness.
  ///    </summary>
  ////////////////////////////////////////////////////////////////////////////////////////////////////

Flowing, left-aligned text (end tag on new line)


  ////////////////////////////////////////////////////////////////////////////////////////////////////
  /// <summary> This example illustrates how documentation entries can be auto-formatted by
  /// AtomineerUtils. The formatting options allow you to choose an ideal compromise between 
  /// readability and compactness.
  /// </summary>
  ////////////////////////////////////////////////////////////////////////////////////////////////////

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 Block Templates, and can be populated using variables such as %fileDescription%, %user%, %copyright% and %filename% to fill in context-specific details. Below are some examples:

Default AtomineerUtils file header
(plain text)


  ////////////////////////////////////////////////////////////////////////////////////////////////////
  // file:      AtomineerUtils\CustomerBookingDlg.cs
  //
  // summary:   Implements the customer booking Dialog
  ////////////////////////////////////////////////////////////////////////////////////////////////////

More comprehensive plain-text example


  ////////////////////////////////////////////////////////////////////////////////////////////////////
  // 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
  ////////////////////////////////////////////////////////////////////////////////////////////////////

XML equivalent of the default file header.


  ////////////////////////////////////////////////////////////////////////////////////////////////////
  /// <file> AtomineerUtils\CustomerBookingDlg.cs. </file>
  /// 
  /// <summary> Implements the customer booking Dialog. </summary>
  ////////////////////////////////////////////////////////////////////////////////////////////////////

Doxygen, Qt and JavaDoc

The AtomineerUtils support for Doxygen, Qt and JavaDoc formats is just as configurable as for Documentation Xml, so most of the above examples can be achieved while using Doxygen/Qt/JavaDoc markup. There are also some Doxygen-specific options. Some examples are:

The default Doxygen (Qt) 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.
  ////////////////////////////////////////////////////////////////////////////////////////////////////

Doxygen (JavaDoc) style
(@ command prefix)


  ////////////////////////////////////////////////////////////////////////////////////////////////////
  /// @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.
  ////////////////////////////////////////////////////////////////////////////////////////////////////

Doxygen (Qt) without the code-element declaration entry


  ////////////////////////////////////////////////////////////////////////////////////////////////////
  /// \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.
  ////////////////////////////////////////////////////////////////////////////////////////////////////

JavaDoc AutoBrief style (no tag on the 'brief' entry), within a block comment
/** * 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. */

Alternative block style
/! \brief Tests skins. \param exampleParam The example parameter. \return true if the test passes, false if the test fails. \author Jason Williams \date 23/04/2009 /

Alternative block style
/** @brief Tests skins. @param exampleParam The example parameter. @return true if the test passes, false if the test fails. @author Jason Williams @date 23/04/2009 */

Compact block 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.