Documentation Xml
The default Atomineer 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/QDoc/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, Atomineer 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 Atomineer 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 QDoc and JavaDoc
The Atomineer support for Doxygen, QDoc and JavaDoc formats is just as configurable as for Documentation Xml,
so most of the above examples can be achieved while using Doxygen/QDoc/JavaDoc markup. There are also some
Doxygen-specific options. Some examples are:
The default Doxygen (QDoc) 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 (QDoc) 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. |
|
Copyright © 1996-2024 Atomineer. All Rights Reserved. Any trademarks reproduced in this text are the property of their respective owners
- Contact us
- Company Info
|
| | |