Changeset 68445 in vbox

Timestamp:

Aug 17, 2017 1:27:05 PM (7 years ago)

Author:

vboxsync

Message:

doc/VBox-CodingGuideslines: use <li> instead of '-' as doxygen expects no blank line between such list items and added another example of code to avoid

File:

• trunk/doc/VBox-CodingGuidelines.cpp (modified) (26 diffs)

trunk/doc/VBox-CodingGuidelines.cpp

@@ -29 +29 @@
  * @section sec_vbox_guideline_compulsory       Compulsory
  *
- *
- *      - The indentation size is 4 chars.
- *
- *      - Tabs are only ever used in makefiles.
- *
- *      - Use RT and VBOX types.
- *
- *      - Use Runtime functions.
- *
- *      - Use the standard bool, uintptr_t, intptr_t and [u]int[1-9+]_t types.
- *
- *      - Avoid using plain unsigned and int.
- *
- *      - Use static wherever possible. This makes the namespace less polluted
+ * <ul>
+ *
+ *   <li> The indentation size is 4 chars.
+ *
+ *   <li> Tabs are only ever used in makefiles.
+ *
+ *   <li> Use RT and VBOX types.
+ *
+ *   <li> Use Runtime functions.
+ *
+ *   <li> Use the standard bool, uintptr_t, intptr_t and [u]int[1-9+]_t types.
+ *
+ *   <li> Avoid using plain unsigned and int.
+ *
+ *   <li> Use static wherever possible. This makes the namespace less polluted
  *        and avoids nasty name clash problems which can occur, especially on
  *        Unix-like systems. (1)  It also simplifies locating callers when
  *        changing it (single source file vs entire VBox tree).
  *
- *      - Public names are of the form Domain[Subdomain[]]Method, using mixed
+ *   <li> Public names are of the form Domain[Subdomain[]]Method, using mixed
  *        casing to mark the words. The main domain is all uppercase.
  *        (Think like java, mapping domain and subdomain to packages/classes.)
  *
- *      - Public names are always declared using the appropriate DECL macro. (2)
- *
- *      - Internal names starts with a lowercased main domain.
- *
- *      - Defines are all uppercase and separate words with underscore.
+ *   <li> Public names are always declared using the appropriate DECL macro. (2)
+ *
+ *   <li> Internal names starts with a lowercased main domain.
+ *
+ *   <li> Defines are all uppercase and separate words with underscore.
  *        This applies to enum values too.
  *
- *      - Typedefs are all uppercase and contain no underscores to distinguish
+ *   <li> Typedefs are all uppercase and contain no underscores to distinguish
  *        them from defines.
  *
- *      - Pointer typedefs start with 'P'. If pointer to const then 'PC'.
- *
- *      - Function typedefs start with 'FN'. If pointer to FN then 'PFN'.
- *
- *      - All files are case sensitive.
- *
- *      - Slashes are unix slashes ('/') runtime converts when necessary.
- *
- *      - char strings are UTF-8.
- *
- *      - Strings from any external source must be treated with utmost care as
+ *   <li> Pointer typedefs start with 'P'. If pointer to const then 'PC'.
+ *
+ *   <li> Function typedefs start with 'FN'. If pointer to FN then 'PFN'.
+ *
+ *   <li> All files are case sensitive.
+ *
+ *   <li> Slashes are unix slashes ('/') runtime converts when necessary.
+ *
+ *   <li> char strings are UTF-8.
+ *
+ *   <li> Strings from any external source must be treated with utmost care as
  *        they do not have to be valid UTF-8.  Only trust internal strings.
  *
- *      - All functions return VBox status codes. There are three general
+ *   <li> All functions return VBox status codes. There are three general
  *        exceptions from this:
- *              -# Predicate functions. These are function which are boolean in
+ *
+ *       <ol>
+ *             <li>Predicate functions. These are function which are boolean in
  *                 nature and usage. They return bool. The function name will
  *                 include 'Has', 'Is' or similar.
- *              -# Functions which by nature cannot possibly fail.
+ *             <li>Functions which by nature cannot possibly fail.
  *                 These return void.
- *              -# "Get"-functions which return what they ask for.
+ *             <li>"Get"-functions which return what they ask for.
  *                 A get function becomes a "Query" function if there is any
  *                 doubt about getting what is ask for.
- *
- *      - VBox status codes have three subdivisions:
- *              -# Errors, which are VERR_ prefixed and negative.
- *              -# Warnings, which are VWRN_ prefixed and positive.
- *              -# Informational, which are VINF_ prefixed and positive.
- *
- *      - Platform/OS operation are generalized and put in the IPRT.
- *
- *      - Other useful constructs are also put in the IPRT.
- *
- *      - The code shall not cause compiler warnings. Check this on ALL
+ *       </ol>
+ *
+ *   <li> VBox status codes have three subdivisions:
+ *         <ol>
+ *           <li> Errors, which are VERR_ prefixed and negative.
+ *           <li> Warnings, which are VWRN_ prefixed and positive.
+ *           <li> Informational, which are VINF_ prefixed and positive.
+ *        </ol>
+ *
+ *   <li> Platform/OS operation are generalized and put in the IPRT.
+ *
+ *   <li> Other useful constructs are also put in the IPRT.
+ *
+ *   <li> The code shall not cause compiler warnings. Check this on ALL
  *        the platforms.
  *
- *      - The use of symbols leading with single or double underscores is
+ *   <li> The use of symbols leading with single or double underscores is
  *        forbidden as that intrudes on reserved compiler/system namespace. (3)
  *
- *      - All files have file headers with $Id and a file tag which describes
+ *   <li> All files have file headers with $Id and a file tag which describes
  *        the file in a sentence or two.
  *        Note: Use the svn-ps.cmd/svn-ps.sh utility with the -a option to add
@@ -106 +112 @@
  *              configured.
  *
- *      - All public functions are fully documented in Doxygen style using the
+ *   <li> All public functions are fully documented in Doxygen style using the
  *        javadoc dialect (using the 'at' instead of the 'slash' as
  *        commandprefix.)
  *
- *      - All structures in header files are described, including all their
+ *   <li> All structures in header files are described, including all their
  *        members. (Doxygen style, of course.)
  *
- *      - All modules have a documentation '\@page' in the main source file
+ *   <li> All modules have a documentation '\@page' in the main source file
  *        which describes the intent and actual implementation.
  *
- *      - Code which is doing things that are not immediately comprehensible
+ *   <li> Code which is doing things that are not immediately comprehensible
  *        shall include explanatory comments.
  *
- *      - Documentation and comments are kept up to date.
- *
- *      - Headers in /include/VBox shall not contain any slash-slash C++
+ *   <li> Documentation and comments are kept up to date.
+ *
+ *   <li> Headers in /include/VBox shall not contain any slash-slash C++
  *        comments, only ANSI C comments!
  *
- *      - Comments on \#else indicates what begins while the comment on a
+ *   <li> Comments on \#else indicates what begins while the comment on a
  *        \#endif indicates what ended.  Only add these when there are more than
  *        a few lines (6-10) of \#ifdef'ed code, otherwise they're just clutter.
- *
+ * </ul>
  *
  * (1) It is common practice on Unix to have a single symbol namespace for an
@@ -150 +156 @@
  * Some facts first:
  *
- *      - On 64-bit Windows the type long remains 32-bit. On nearly all other
+ * <ul>
+ *
+ *   <li> On 64-bit Windows the type long remains 32-bit. On nearly all other
  *        64-bit platforms long is 64-bit.
  *
- *      - On all 64-bit platforms we care about, int is 32-bit, short is 16 bit
+ *   <li> On all 64-bit platforms we care about, int is 32-bit, short is 16 bit
  *        and char is 8-bit.
  *        (I don't know about any platforms yet where this isn't true.)
  *
- *      - size_t, ssize_t, uintptr_t, ptrdiff_t and similar are all 64-bit on
+ *   <li> size_t, ssize_t, uintptr_t, ptrdiff_t and similar are all 64-bit on
  *        64-bit platforms. (These are 32-bit on 32-bit platforms.)
  *
- *      - There is no inline assembly support in the 64-bit Microsoft compilers.
- *
+ *   <li> There is no inline assembly support in the 64-bit Microsoft compilers.
+ *
+ * </ul>
  *
  * Now for the guidelines:
  *
- *      - Never, ever, use int, long, ULONG, LONG, DWORD or similar to cast a
+ * <ul>
+ *
+ *   <li> Never, ever, use int, long, ULONG, LONG, DWORD or similar to cast a
  *        pointer to integer.  Use uintptr_t or intptr_t. If you have to use
  *        NT/Windows types, there is the choice of ULONG_PTR and DWORD_PTR.
  *
- *      - Avoid where ever possible the use of the types 'long' and 'unsigned
+ *   <li> Avoid where ever possible the use of the types 'long' and 'unsigned
  *        long' as these differs in size between windows and the other hosts
  *        (see above).
  *
- *      - RT_OS_WINDOWS is defined to indicate Windows. Do not use __WIN32__,
+ *   <li> RT_OS_WINDOWS is defined to indicate Windows. Do not use __WIN32__,
  *        __WIN64__ and __WIN__ because they are all deprecated and scheduled
  *        for removal (if not removed already). Do not use the compiler
@@ -194 +205 @@
  *        @endcode
  *
- *      - There are RT_OS_xxx defines for each OS, just like RT_OS_WINDOWS
+ *   <li> There are RT_OS_xxx defines for each OS, just like RT_OS_WINDOWS
  *        mentioned above. Use these defines instead of any predefined
  *        compiler stuff or defines from system headers.
  *
- *      - RT_ARCH_X86 is defined when compiling for the x86 the architecture.
+ *   <li> RT_ARCH_X86 is defined when compiling for the x86 the architecture.
  *        Do not use __x86__, __X86__, __[Ii]386__, __[Ii]586__, or similar
  *        for this purpose.
  *
- *      - RT_ARCH_AMD64 is defined when compiling for the AMD64 architecture.
+ *   <li> RT_ARCH_AMD64 is defined when compiling for the AMD64 architecture.
  *        Do not use __AMD64__, __amd64__ or __x64_86__.
  *
- *      - Take care and use size_t when you have to, esp. when passing a pointer
+ *   <li> Take care and use size_t when you have to, esp. when passing a pointer
  *        to a size_t as a parameter.
  *
- *      - Be wary of type promotion to (signed) integer. For example the
+ *   <li> Be wary of type promotion to (signed) integer. For example the
  *        following will cause u8 to be promoted to int in the shift, and then
  *        sign extended in the assignment 64-bit:
@@ -217 +228 @@
  *        @endcode
  *
+ * </ul>
  *
  * @subsection sec_vbox_guideline_compulsory_cppmain   C++ guidelines for Main
@@ -224 +236 @@
  * instead of more for the following reasons:
  *
- *  -  Template code is harder to read and understand. Custom templates create
- *     territories which only the code writer understands.
- *
- *  -  Errors in using templates create terrible C++ compiler messages.
- *
- *  -  Template code is really hard to look at in a debugger.
- *
- *  -  Templates slow down the compiler a lot.
- *
- *  In particular, the following bits should be considered deprecated and should
- *  NOT be used in new code:
- *
- *  -  everything in include/iprt/cpputils.h (auto_ref_ptr, exception_trap_base,
- *     char_auto_ptr and friends)
- *
- *  Generally, in many cases, a simple class with a proper destructor can achieve
- *  the same effect as a 1,000-line template include file, and the code is
- *  much more accessible that way.
- *
- *  Using standard STL templates like std::list, std::vector and std::map is OK.
- *  Exceptions are:
- *
- *  -  Guest Additions because we don't want to link against libstdc++ there.
- *
- *  -  std::string should not be used because we have iprt::MiniString and
+ * <ul>
+ *
+ *   <li>  Template code is harder to read and understand. Custom templates create
+ *         territories which only the code writer understands.
+ *
+ *   <li>  Errors in using templates create terrible C++ compiler messages.
+ *
+ *   <li>  Template code is really hard to look at in a debugger.
+ *
+ *   <li>  Templates slow down the compiler a lot.
+ *
+ * </ul>
+ *
+ * In particular, the following bits should be considered deprecated and should
+ * NOT be used in new code:
+ *
+ * <ul>
+ *
+ *   <li>  everything in include/iprt/cpputils.h (auto_ref_ptr, exception_trap_base,
+ *         char_auto_ptr and friends)
+ *
+ * </ul>
+ *
+ * Generally, in many cases, a simple class with a proper destructor can achieve
+ * the same effect as a 1,000-line template include file, and the code is
+ * much more accessible that way.
+ *
+ * Using standard STL templates like std::list, std::vector and std::map is OK.
+ * Exceptions are:
+ *
+ * <ul>
+ *
+ *   <li>  Guest Additions because we don't want to link against libstdc++ there.
+ *
+ *   <li>  std::string should not be used because we have iprt::MiniString and
  *     com::Utf8Str which can convert efficiently with COM's UTF-16 strings.
  *
- *  -  std::auto_ptr<> in general; that part of the C++ standard is just broken.
+ *   <li>  std::auto_ptr<> in general; that part of the C++ standard is just broken.
  *     Write a destructor that calls delete.
  *
+ * </ul>
  *
  * @subsection sec_vbox_guideline_compulsory_cppqtgui   C++ guidelines for the Qt GUI
@@ -262 +285 @@
  * the following rules should be respected:
  *
- * - GUI classes which correspond to GUI tasks should be prefixed by UI (no VBox anymore)
- *
- * - Classes which extents some of the Qt classes should be prefix by QI
- *
- * - General task classes should be prefixed by C
- *
- * - Slots are prefixed by slt -> sltName
- *
- * - Signals are prefixed by sig -> sigName
- *
- * - Use Qt classes for lists, strings and so on, the use of STL classes should
+ * <ul>
+ *
+ *   <li> GUI classes which correspond to GUI tasks should be prefixed by UI (no VBox anymore)
+ *
+ *   <li> Classes which extents some of the Qt classes should be prefix by QI
+ *
+ *   <li> General task classes should be prefixed by C
+ *
+ *   <li> Slots are prefixed by slt -> sltName
+ *
+ *   <li> Signals are prefixed by sig -> sigName
+ *
+ *   <li> Use Qt classes for lists, strings and so on, the use of STL classes should
  *   be avoided
  *
- * - All files like .cpp, .h, .ui, which belong together are located in the
+ *   <li> All files like .cpp, .h, .ui, which belong together are located in the
  *   same directory and named the same
+ *
+ * </ul>
  *
  *
@@ -285 +312 @@
  * There are a couple of common pitfalls worth mentioning:
  *
- *      - Never do repeated //interface[@name=...] and //enum[@name=...] lookups
+ * <ul>
+ *
+ *   <li> Never do repeated //interface[\@name=...] and //enum[\@name=...] lookups
  *        because they are expensive. Instead delcare xsl:key elements for these
  *        searches and do the lookup using the key() function. xsltproc uses
  *        (per current document) hash tables for each xsl:key, i.e. very fast.
  *
- *      - When output type is 'text' make sure to call xsltprocNewlineOutputHack
+ *   <li> When output type is 'text' make sure to call xsltprocNewlineOutputHack
  *        from typemap-shared.inc.xsl every few KB of output, or xsltproc will
  *        end up wasting all the time reallocating the output buffer.
  *
+ * </ul>
  *
  * @subsection sec_vbox_guideline_compulsory_doxygen    Doxygen Comments
@@ -303 +333 @@
  * A couple of hints on how to best write doxygen comments:
  *
- *      - A good class, method, function, structure or enum doxygen comment
+ * <ul>
+ *
+ *   <li> A good class, method, function, structure or enum doxygen comment
  *        starts with a one line sentence giving a brief description of the
  *        item.  Details comes in a new paragraph (after blank line).
  *
- *      - Except for list generators like \@todo, \@cfgm, \@gcfgm and others,
+ *   <li> Except for list generators like \@todo, \@cfgm, \@gcfgm and others,
  *        all doxygen comments are related to things in the code.  So, for
  *        instance you DO NOT add a doxygen \@note comment in the middle of a
@@ -313 +345 @@
  *        comment like 'Note! blah, very importan blah!'
  *
- *      - We do NOT use TODO/XXX/BUGBUG or similar markers in the code to flag
+ *   <li> We do NOT use TODO/XXX/BUGBUG or similar markers in the code to flag
  *        things needing fixing later, we always use \@todo doxygen comments.
  *
- *      - There is no colon after the \@todo.  And it is ALWAYS in a doxygen
+ *   <li> There is no colon after the \@todo.  And it is ALWAYS in a doxygen
  *        comment.
  *
- *      - The \@retval tag is used to explain status codes a method/function may
+ *   <li> The \@retval tag is used to explain status codes a method/function may
  *        returns.  It is not used to describe output parameters, that is done
  *        using the \@param or \@param[out] tag.
  *
+ * </ul>
+ *
  * See https://www.stack.nl/~dimitri/doxygen/manual/index.html for the official
  * doxygen documention.
@@ -335 +369 @@
  * @subsection sec_vbox_guideline_optional_layout   The code layout
  *
- *      - Max line length is 130 chars.  Exceptions are table-like
+ * <ul>
+ *
+ *   <li> Max line length is 130 chars.  Exceptions are table-like
  *        code/initializers and Log*() statements (don't waste unnecessary
  *        vertical space on debug logging).
  *
- *      - Comments should try stay within the usual 80 columns as these are
+ *   <li> Comments should try stay within the usual 80 columns as these are
  *        denser and too long lines may be harder to read.
  *
- *      - Curly brackets are not indented.  Example:
+ *   <li> Curly brackets are not indented.  Example:
  *        @code
  *              if (true)
@@ -356 +392 @@
  *        @endcode
  *
- *      - Space before the parentheses when it comes after a C keyword.
- *
- *      - No space between argument and parentheses. Exception for complex
+ *   <li> Space before the parentheses when it comes after a C keyword.
+ *
+ *   <li> No space between argument and parentheses. Exception for complex
  *        expression.  Example:
  *        @code
@@ -364 +400 @@
  *        @endcode
  *
- *      - The else of an if is always the first statement on a line. (No curly
+ *   <li> The else of an if is always the first statement on a line. (No curly
  *        stuff before it!)
  *
- *      - else and if go on the same line if no { compound statement }
+ *   <li> else and if go on the same line if no { compound statement }
  *        follows the if.  Example:
  *        @code
@@ -380 +416 @@
  *        @endcode
  *
- *
- *      - Slightly complex boolean expressions are split into multiple lines,
+ *   <li> Slightly complex boolean expressions are split into multiple lines,
  *        putting the operators first on the line and indenting it all according
  *        to the nesting of the expression. The purpose is to make it as easy as
@@ -390 +425 @@
  *        @endcode
  *
- *      - When 'if' or  'while' statements gets long, the closing parentheses
+ *   <li> When 'if' or  'while' statements gets long, the closing parentheses
  *        goes right below the opening parentheses.  This may be applied to
  *        sub-expression.  Example:
@@ -406 +441 @@
  *        @endcode
  *
- *      - The case is indented from the switch (to avoid having the braces for
+ *   <li> The case is indented from the switch (to avoid having the braces for
  *        the 'case' at the same level as the 'switch' statement).
  *
- *      - If a case needs curly brackets they contain the entire case, are not
+ *   <li> If a case needs curly brackets they contain the entire case, are not
  *        indented from the case, and the break or return is placed inside them.
  *        Example:
@@ -427 +462 @@
  *        @endcode
  *
- *      - In a do while construction, the while is on the same line as the
+ *   <li> In a do while construction, the while is on the same line as the
  *        closing "}" if any are used.
  *        Example:
@@ -438 +473 @@
  *        @endcode
  *
- *      - Comments are in C style.  C++ style comments are used for temporary
+ *   <li> Comments are in C style.  C++ style comments are used for temporary
  *        disabling a few lines of code.
  *
- *      - No unnecessary parentheses in expressions (just don't over do this
+ *   <li> No unnecessary parentheses in expressions (just don't over do this
  *        so that gcc / msc starts bitching). Find a correct C/C++ operator
  *        precedence table if needed.
  *
- *      - 'for (;;)' is preferred over 'while (true)' and 'while (1)'.
- *
- *      - Parameters are indented to the start parentheses when breaking up
+ *   <li> 'for (;;)' is preferred over 'while (true)' and 'while (1)'.
+ *
+ *   <li> Parameters are indented to the start parentheses when breaking up
  *        function calls, declarations or prototypes.  (This is in line with
  *        how 'if', 'for' and 'while' statements are done as well.) Example:
@@ -464 +499 @@
  *        @endcode
  *
- *      - That Dijkstra is dead is no excuse for using gotos.
- *
- *      - Using do-while-false loops to avoid gotos is considered very bad form.
+ *   <li> That Dijkstra is dead is no excuse for using gotos.
+ *
+ *   <li> Using do-while-false loops to avoid gotos is considered very bad form.
  *        They create hard to read code.  They tend to be either too short (i.e.
  *        pointless) or way to long (split up the function already), making
@@ -475 +510 @@
  *        the code up into more functions!
  *
+ *   <li> Avoid code like
+ *        @code
+ *              int foo;
+ *              int rc;
+ *              ...
+ *              rc = FooBar();
+ *              if (RT_SUCCESS(rc))
+ *              {
+ *                  foo = getFoo();
+ *                  ...
+ *                  pvBar = RTMemAlloc(sizeof(*pvBar));
+ *                  if (!pvBar)
+ *                     rc = VERR_NO_MEMORY;
+ *              }   
+ *              if (RT_SUCCESS(rc))
+ *              {
+ *                  buzz = foo;
+ *                  ...
+ *              }
+ *        @endcode
+ *        The intention of such code is probably to save some horizontal space
+ *        but unfortunately it's hard to read and the scope of certain varables
+ *        (e.g. foo in this example) is not optimal. Better use the following
+ *        style:
+ *        @code
+ *              int rc;
+ *              ...
+ *              rc = FooBar();
+ *              if (RT_SUCCESS(rc))
+ *              {
+ *                  int foo = getFoo();
+ *                  ...
+ *                  pvBar = RTMemAlloc(sizeof(*pvBar));
+ *                  if (pvBar)
+ *                  {
+ *                      buzz = foo;
+ *                      ...
+ *                  }
+ *                  else
+ *                      rc = VERR_NO_MEMORY;
+ *              }
+ *        @endcode
+ *
+ * </ul>
  *
  * @subsection sec_vbox_guideline_optional_prefix   Variable / Member Prefixes
@@ -485 +564 @@
  * The prefixes:
  *
- *      - The 'g_' (or 'g') prefix means a global variable, either on file or module level.
- *
- *      - The 's_' (or 's') prefix means a static variable inside a function or
+ * <ul>
+ *
+ *   <li> The 'g_' (or 'g') prefix means a global variable, either on file or module level.
+ *
+ *   <li> The 's_' (or 's') prefix means a static variable inside a function or
  *        class.  This is not used for static variables on file level, use 'g_'
  *        for those (logical, right).
  *
- *      - The 'm_' (or 'm') prefix means a class data member.
+ *   <li> The 'm_' (or 'm') prefix means a class data member.
  *
  *        In new code in Main, use "m_" (and common sense).  As an exception,
@@ -501 +582 @@
  *        already which is clear enough.
  *
- *      - The 'a_' prefix means a parameter (argument) variable.  This is
+ *   <li> The 'a_' prefix means a parameter (argument) variable.  This is
  *        sometimes written 'a' in parts of the source code that does not use
  *        the array prefix.
  *
- *      - The 'p' prefix means pointer.  For instance 'pVM' is pointer to VM.
- *
- *      - The 'r' prefix means that something is passed by reference.
- *
- *      - The 'k' prefix means that something is a constant.  For instance
+ *   <li> The 'p' prefix means pointer.  For instance 'pVM' is pointer to VM.
+ *
+ *   <li> The 'r' prefix means that something is passed by reference.
+ *
+ *   <li> The 'k' prefix means that something is a constant.  For instance
  *        'enum { kStuff };'.  This is usually not used in combination with
  *        'p', 'r' or any such thing, it's main main use is to make enums
  *        easily identifiable.
  *
- *      - The 'a' prefix means array.  For instance 'aPages' could be read as
+ *   <li> The 'a' prefix means array.  For instance 'aPages' could be read as
  *        array of pages.
  *
- *      - The 'c' prefix means count.  For instance 'cbBlock' could be read,
+ *   <li> The 'c' prefix means count.  For instance 'cbBlock' could be read,
  *        count of bytes in block. (1)
  *
- *      - The 'cx' prefix means width (count of 'x' units).
- *
- *      - The 'cy' prefix means height (count of 'y' units).
- *
- *      - The 'x', 'y' and 'z' prefix refers to the x-, y- , and z-axis
+ *   <li> The 'cx' prefix means width (count of 'x' units).
+ *
+ *   <li> The 'cy' prefix means height (count of 'y' units).
+ *
+ *   <li> The 'x', 'y' and 'z' prefix refers to the x-, y- , and z-axis
  *        respectively.
  *
- *      - The 'off' prefix means offset.
- *
- *      - The 'i' or 'idx' prefixes usually means index.  Although the 'i' one
+ *   <li> The 'off' prefix means offset.
+ *
+ *   <li> The 'i' or 'idx' prefixes usually means index.  Although the 'i' one
  *        can sometimes just mean signed integer.
  *
- *      - The 'i[1-9]+' prefix means a fixed bit size variable.  Frequently
+ *   <li> The 'i[1-9]+' prefix means a fixed bit size variable.  Frequently
  *        used with the int[1-9]+_t types where the width is really important.
  *        In most cases 'i' is more appropriate.  [type]
  *
- *      - The 'e' (or 'enm') prefix means enum.
- *
- *      - The 'u' prefix usually means unsigned integer.  Exceptions follows.
- *
- *      - The 'u[1-9]+' prefix means a fixed bit size variable.  Frequently
+ *   <li> The 'e' (or 'enm') prefix means enum.
+ *
+ *   <li> The 'u' prefix usually means unsigned integer.  Exceptions follows.
+ *
+ *   <li> The 'u[1-9]+' prefix means a fixed bit size variable.  Frequently
  *        used with the uint[1-9]+_t types and with bitfields where the width is
  *        really important.  In most cases 'u' or 'b' (byte) would be more
  *        appropriate.  [type]
  *
- *      - The 'b' prefix means byte or bytes.  [type]
- *
- *      - The 'f' prefix means flags.  Flags are unsigned integers of some kind
+ *   <li> The 'b' prefix means byte or bytes.  [type]
+ *
+ *   <li> The 'f' prefix means flags.  Flags are unsigned integers of some kind
  *        or booleans.
  *
- *      - TODO: need prefix for real float.  [type]
- *
- *      - The 'rd' prefix means real double and is used for 'double' variables.
+ *   <li> TODO: need prefix for real float.  [type]
+ *
+ *   <li> The 'rd' prefix means real double and is used for 'double' variables.
  *        [type]
  *
- *      - The 'lrd' prefix means long real double and is used for 'long double'
+ *   <li> The 'lrd' prefix means long real double and is used for 'long double'
  *        variables. [type]
  *
- *      - The 'ch' prefix means a char, the (signed) char type.  [type]
- *
- *      - The 'wc' prefix means a wide/windows char, the RTUTF16 type.  [type]
- *
- *      - The 'uc' prefix means a Unicode Code point, the RTUNICP type.  [type]
- *
- *      - The 'uch' prefix means unsigned char.  It's rarely used.  [type]
- *
- *      - The 'sz' prefix means zero terminated character string (array of
+ *   <li> The 'ch' prefix means a char, the (signed) char type.  [type]
+ *
+ *   <li> The 'wc' prefix means a wide/windows char, the RTUTF16 type.  [type]
+ *
+ *   <li> The 'uc' prefix means a Unicode Code point, the RTUNICP type.  [type]
+ *
+ *   <li> The 'uch' prefix means unsigned char.  It's rarely used.  [type]
+ *
+ *   <li> The 'sz' prefix means zero terminated character string (array of
  *        chars). (UTF-8)
  *
- *      - The 'wsz' prefix means zero terminated wide/windows character string
+ *   <li> The 'wsz' prefix means zero terminated wide/windows character string
  *        (array of RTUTF16).
  *
- *      - The 'usz' prefix means zero terminated Unicode string (array of
+ *   <li> The 'usz' prefix means zero terminated Unicode string (array of
  *        RTUNICP).
  *
- *      - The 'str' prefix means C++ string; either a std::string or, in Main,
+ *   <li> The 'str' prefix means C++ string; either a std::string or, in Main,
  *        a Utf8Str or, in Qt, a QString.  When used with 'p', 'r', 'a' or 'c'
  *        the first letter should be capitalized.
  *
- *      - The 'bstr' prefix, in Main, means a UTF-16 Bstr. When used with 'p',
+ *   <li> The 'bstr' prefix, in Main, means a UTF-16 Bstr. When used with 'p',
  *        'r', 'a' or 'c' the first letter should be capitalized.
  *
- *      - The 'pfn' prefix means pointer to function. Common usage is 'pfnCallback'
+ *   <li> The 'pfn' prefix means pointer to function. Common usage is 'pfnCallback'
  *        and such like.
  *
- *      - The 'psz' prefix is a combination of 'p' and 'sz' and thus means
+ *   <li> The 'psz' prefix is a combination of 'p' and 'sz' and thus means
  *        pointer to a zero terminated character string. (UTF-8)
  *
- *      - The 'pcsz' prefix is used to indicate constant string pointers in
+ *   <li> The 'pcsz' prefix is used to indicate constant string pointers in
  *        parts of the code.  Most code uses 'psz' for const and non-const
  *        string pointers, so please ignore this one.
  *
- *      - The 'l' prefix means (signed) long.  We try avoid using this,
+ *   <li> The 'l' prefix means (signed) long.  We try avoid using this,
  *        expecially with the 'LONG' types in Main as these are not 'long' on
  *        64-bit non-Windows platforms and can cause confusion. Alternatives:
  *        'i' or 'i32'.  [type]
  *
- *      - The 'ul' prefix means unsigned long.  We try avoid using this,
+ *   <li> The 'ul' prefix means unsigned long.  We try avoid using this,
  *        expecially with the 'ULONG' types in Main as these are not 'unsigned
  *        long' on 64-bit non-Windows platforms and can cause confusion.
  *        Alternatives: 'u' or 'u32'.  [type]
  *
+ * </ul>
  *
  * (1)  Except in the occasional 'pcsz' prefix, the 'c' prefix is never ever
@@ -609 +691 @@
  * @subsection sec_vbox_guideline_optional_misc     Misc / Advice / Stuff
  *
- *      - When writing code think as the reader.
- *
- *      - When writing code think as the compiler. (2)
- *
- *      - When reading code think as if it's full of bugs - find them and fix them.
- *
- *      - Pointer within range tests like:
+ * <ul>
+ *
+ *   <li> When writing code think as the reader.
+ *
+ *   <li> When writing code think as the compiler. (2)
+ *
+ *   <li> When reading code think as if it's full of bugs - find them and fix them.
+ *
+ *   <li> Pointer within range tests like:
  *        @code
  *          if ((uintptr_t)pv >= (uintptr_t)pvBase && (uintptr_t)pv < (uintptr_t)pvBase + cbRange)
@@ -625 +709 @@
  *        Which is shorter and potentially faster. (1)
  *
- *      - Avoid unnecessary casting. All pointers automatically cast down to
+ *   <li> Avoid unnecessary casting. All pointers automatically cast down to
  *        void *, at least for non class instance pointers.
  *
- *      - It's very very bad practise to write a function larger than a
+ *   <li> It's very very bad practise to write a function larger than a
  *        screen full (1024x768) without any comprehensibility and explaining
  *        comments.
  *
- *      - More to come....
- *
+ *   <li> More to come....
+ *
+ * </ul>
  *
  * (1)  Important, be very careful with the casting. In particular, note that
@@ -684 +769 @@
  * Before checking in:
  *
- *      - Check Tinderbox and make sure the tree is green across all platforms. If it's
+ * <ul>
+ *
+ *   <li> Check Tinderbox and make sure the tree is green across all platforms. If it's
  *        red on a platform, don't check in. If you want, warn in the \#vbox channel and
  *        help make the responsible person fix it.
  *        NEVER CHECK IN TO A BROKEN BUILD.
  *
- *      - When checking in keep in mind that a commit is atomic and that the Tinderbox and
+ *   <li> When checking in keep in mind that a commit is atomic and that the Tinderbox and
  *        developers are constantly checking out the tree. Therefore do not split up the
  *        commit unless it's into 100% independent parts. If you need to split it up in order
  *        to have sensible commit comments, make the sub-commits as rapid as possible.
  *
- *      - If you make a user visible change, such as fixing a reported bug,
+ *   <li> If you make a user visible change, such as fixing a reported bug,
  *        make sure you add an entry to doc/manual/user_ChangeLogImpl.xml.
  *
- *      - If you are adding files make sure set the right attributes.
+ *   <li> If you are adding files make sure set the right attributes.
  *        svn-ps.sh/cmd was created for this purpose, please make use of it.
  *
+ * </ul>
  *
  * After checking in:
  *
- *      - After checking-in, you watch Tinderbox until your check-ins clear. You do not
+ * <ul>
+ *
+ *   <li> After checking-in, you watch Tinderbox until your check-ins clear. You do not
  *        go home. You do not sleep. You do not log out or experiment with drugs. You do
  *        not become unavailable. If you break the tree, add a comment saying that you're
@@ -709 +799 @@
  *        out the change.
  *
+ * </ul>
+ *
  * (Inspired by mozilla tree rules.)
  */