Index: /trunk/include/iprt/cdefs.h
===================================================================
--- /trunk/include/iprt/cdefs.h	(revision 55950)
+++ /trunk/include/iprt/cdefs.h	(revision 55951)
@@ -1321,4 +1321,6 @@
  * A few notes about the usage:
  *
+ *      - Generally, order your code use RT_LIKELY() instead of RT_UNLIKELY().
+ *
  *      - Generally, use RT_UNLIKELY() with error condition checks (unless you
  *        have some _strong_ reason to do otherwise, in which case document it),
@@ -1328,5 +1330,5 @@
  *      - Other than that, if you don't know the likelihood of a test succeeding
  *        from empirical or other 'hard' evidence, don't make predictions unless
- *        you happen to be a Dirk Gently.
+ *        you happen to be a Dirk Gently character.
  *
  *      - These macros are meant to be used in places that get executed a lot. It
@@ -1336,5 +1338,5 @@
  *
  *      - Note that RT_SUCCESS() and RT_FAILURE() already makes use of RT_LIKELY()
- *        and RT_UNLIKELY(). Should you wish for prediction free status checks,
+ *        and RT_UNLIKELY().  Should you wish for prediction free status checks,
  *        use the RT_SUCCESS_NP() and RT_FAILURE_NP() macros instead.
  *
@@ -1342,5 +1344,5 @@
  * @returns the boolean result of the expression.
  * @param   expr        The expression that's very likely to be true.
- * @see RT_UNLIKELY
+ * @see     RT_UNLIKELY
  */
 /** @def RT_UNLIKELY
@@ -1351,5 +1353,10 @@
  * @returns the boolean result of the expression.
  * @param   expr        The expression that's very unlikely to be true.
- * @see RT_LIKELY
+ * @see     RT_LIKELY
+ *
+ * @remarks Please use RT_LIKELY() instead wherever possible!  That gives us a
+ *          better chance of the windows compilers to generate favorable code
+ *          too.  The belief is that the compiler will by default assume the
+ *          if-case is more likely than the else-case.
  */
 #if defined(__GNUC__)
Index: /trunk/include/iprt/err.h
===================================================================
--- /trunk/include/iprt/err.h	(revision 55950)
+++ /trunk/include/iprt/err.h	(revision 55951)
@@ -162,6 +162,9 @@
 
 /** @def RT_FAILURE
- * Check for failure. We don't expect in normal cases, that is the code path depending on
- * this check is normally NOT taken. To prevent any prediction use RT_FAILURE_NP instead.
+ * Check for failure, predicting unlikely.
+ *
+ * We don't expect in normal cases, that is the code path depending on this
+ * check is normally NOT taken. To prevent any prediction use RT_FAILURE_NP
+ * instead.
  *
  * @returns true if rc indicates failure.
@@ -169,9 +172,13 @@
  *
  * @param   rc  The iprt status code to test.
+ *
+ * @remarks Please structure your code to use the RT_SUCCESS() macro instead of
+ *          RT_FAILURE() where possible, as that gives us a better shot at good
+ *          code with the windows compilers.
  */
 #define RT_FAILURE(rc)      ( RT_UNLIKELY(!RT_SUCCESS_NP(rc)) )
 
 /** @def RT_FAILURE_NP
- * Check for failure. Don't predict the result.
+ * Check for failure, no prediction.
  *
  * @returns true if rc indicates failure.