fix doxygen for IceBuildDefs.h

src/IceBuildDefs.h

@@ -8,25 +8,88 @@
 //===----------------------------------------------------------------------===//
 ///
 /// \file
-/// \brief Defines constexpr functions to query various #define values.
-///
+/// \brief Define the Ice::BuildDefs namespace
 //===----------------------------------------------------------------------===//
 
 #ifndef SUBZERO_SRC_ICEBUILDDEFS_H
 #define SUBZERO_SRC_ICEBUILDDEFS_H
 
 namespace Ice {
+  /// \brief Defines constexpr functions that express various Subzero build
+  /// system defined values.
+  ///
+  /// These resulting constexpr functions allow code to in effect be
+  /// conditionally compiled without having to do this using the older C++
+  /// preprocessor solution.
+
+  /** \verbatim
+
+   For example whenever the value of FEATURE_SUPPORTED is needed, instead
+   of (except in these constexpr functions):
+
+   #if FEATURE_SUPPORTED ...
+   ...
+   #endif
+
+   We can have:
+
+   namespace Ice {
+   namespace BuildDefs {
+
+   // Use this form when FEATURE_SUPPORTED is guaranteed to be defined on the
+   // C++ compiler command line as 0 or 1.
+   constexpr bool hasFeature() { return FEATURE_SUPPORTED; }
+
+   or
+
+   // Use this form when FEATURE_SUPPORTED may not necessarily be defined on
+   // the C++ compiler command line.
+   constexpr bool hasFeature() {
+   #if FEATURE_SUPPORTED
+     return true;
+   #else // !FEATURE_SUPPORTED
+     return false;
+   #endif // !FEATURE_SUPPORTED
+   }
+
+   ...} // end of namespace BuildDefs
+   } // end of namespace Ice
+
+
+   And later in the code:
+
+   if (Ice::BuildDefs::hasFeature() {
+      ...
+   }
+
+   \endverbatim
+
+   Since hasFeature() returns a constexpr, an optimizing compiler will know to
+   keep or discard the above fragment. In addition, the code will always be
+   looked at by the compiler which eliminates the problem with defines in that
+   if you don't build that variant, you don't even know if the code would
+   compile unless you build with that variant.
+
+    **/
+
+
 namespace BuildDefs {
 
 // The ALLOW_* etc. symbols must be #defined to zero or non-zero.
+/// Return true if ALLOW_DISABLE_IR_GEN is defined as a non-zero value
 constexpr bool disableIrGen() { return ALLOW_DISABLE_IR_GEN; }
+/// Return true if ALLOW_DUMP is defined as a non-zero value
 constexpr bool dump() { return ALLOW_DUMP; }
+/// Return true if ALLOW_LLVM_CL is defined as a non-zero value
 constexpr bool llvmCl() { return ALLOW_LLVM_CL; }
+/// Return true if ALLOW_LLVM_IR is defined as a non-zero value
 constexpr bool llvmIr() { return ALLOW_LLVM_IR; }
+/// Return true if ALLOW_LLVM_IR_AS_INPUT is defined as a non-zero value
 constexpr bool llvmIrAsInput() { return ALLOW_LLVM_IR_AS_INPUT; }
+/// Return true if ALLOW_MINIMAL_BUILD is defined as a non-zero value
 constexpr bool minimal() { return ALLOW_MINIMAL_BUILD; }
 
-// NDEBUG can be undefined, or defined to something arbitrary.
+/// Return true if NDEBUG is defined
 constexpr bool asserts() {
 #ifdef NDEBUG
   return false;
@@ -35,8 +98,7 @@ constexpr bool asserts() {
 #endif // !NDEBUG
 }
 
-// PNACL_BROWSER_TRANSLATOR can be undefined, or defined to something non-zero
-// to indicate a browser-based translator.
+/// Return true if PNACL_BROWSER_TRANSLATOR is defined
 constexpr bool browser() {
 #if PNACL_BROWSER_TRANSLATOR
   return true;
@@ -45,7 +107,7 @@ constexpr bool browser() {
 #endif // !PNACL_BROWSER_TRANSLATOR
 }
 
-// ALLOW_EXTRA_VALIDATION can be undefined, or defined to something non-zero.
+/// Return true if ALLOW_EXTRA_VALIDATION is defined
 constexpr bool extraValidation() {
 #if ALLOW_EXTRA_VALIDATION
   return true;