fix doxygen for IceBuildDefs.h

This is an attempt to make IceBuildDefs more understandable
in the Doxygen produced output, as well as when the various
functions are later referenced from other parts of the subzero docs.

If you look at the doxygen for both the file and the IceBuildDefs namespace, I think it's definitely much
clearer.

I'm still learning Doxygen and always see new things and more that I could have done but Rome was not built in a day.

In my browser:
file:///home/rkotler/nacl_dir/native_client/toolchain_build/src/subzero/docs/html/namespaceIce_1_1BuildDefs.html

and

file:///home/rkotler/nacl_dir/native_client/toolchain_build/src/subzero/docs/html/IceBuildDefs_8h.html

BUG=
R=stichnot@chromium.org

Review URL: https://codereview.chromium.org/1519113003 .

Patch from Reed Kotler <rkotlerimgtec@gmail.com>.

src/IceBuildDefs.h

diff --git a/src/IceBuildDefs.h b/src/IceBuildDefs.h
index 9269697..5dabd9a 100644
--- a/src/IceBuildDefs.h
+++ b/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 @@
 #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 @@
 #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;