fix doxygen for IceBuildDefs.h

src/IceBuildDefs.h

 //===- subzero/src/IceBuildDefs.h - Translator build defines ----*- C++ -*-===//
 //
 //                        The Subzero Code Generator
 //
 // This file is distributed under the University of Illinois Open Source
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
 ///
 /// \file
-/// \brief Defines constexpr functions to query various #define values.
-///
+/// \brief Define the Ice::BuildDefs Namespace

[Jim Stichnoth, 2015/12/12 00:04:34]

lowercase "namespace"

[rkotlerimgtec, 2015/12/12 02:23:35]

Done.

 //===----------------------------------------------------------------------===//
 
 #ifndef SUBZERO_SRC_ICEBUILDDEFS_H
 #define SUBZERO_SRC_ICEBUILDDEFS_H
 
 namespace Ice {
+  /// \brief Defines constexpr functions that express various subzero build

[Jim Stichnoth, 2015/12/12 00:04:33]

Capitalize Subzero

[rkotlerimgtec, 2015/12/12 02:23:35]

Done.

+  /// system defined values.
+  ///
+  /// These resulting constexpr functions allow code to in effect be
+  /// conditionally compiled without having to do this using the older c++

[Jim Stichnoth, 2015/12/12 00:04:34]

C++

[rkotlerimgtec, 2015/12/12 02:23:35]

Done.

+  /// preprocessor solution.
+  /** \verbatim

[Jim Stichnoth, 2015/12/12 00:04:34]

It seems like this \verbatim section could/should start one paragraph earlier,
after the \brief, but I don't know doxygen well enough.  What do you think?

[rkotlerimgtec, 2015/12/12 02:23:35]

Verbatim does not flow at all. It's verbatim so I'm just using
it here for code that I want to be formatted exactly as I
typed it in. The verbatim should actually end earlier and revert
to flow which I'm going to change it to do. If you make your
browser window more narrow or wide you will see all the text
flowing.

+   For example whenever the value of FEATURE_SUPPORTED is needed, instead of
+   (except for in these constexpr functions):
+
+   #if FEATURE_SUPPORTED ...
+   ...
+   #endif
+
+   We can have:
+   namespace Ice {
+   namespace BuildDefs
+   ....
+   constexpr bool hasFeature() { return FEATURE_SUPPORTED; }

[Jim Stichnoth, 2015/12/12 00:04:33]

I suggest adding a comment above, something like:

// Use this form when FEATURE_SUPPORTED is guaranteed to be defined on the C++
compiler command line as 0 or 1.

[rkotlerimgtec, 2015/12/12 02:23:35]

Done.

+
+   or
+
+   constexpr bool hasFeature() {

[Jim Stichnoth, 2015/12/12 00:04:34]

Likewise, a comment like:

// Use this form when FEATURE_SUPPORTED may not necessarily be defined on the
C++ compiler command line.

[rkotlerimgtec, 2015/12/12 02:23:35]

Done.

+   #ifdef FEATURE_SUPPORTED

[Jim Stichnoth, 2015/12/12 00:04:34]

With one exception, Subzero uses "#if" instead of "#ifdef", so that if a
specific -D is omitted, its value is taken as 0.  (The one exception is NDEBUG
which we don't really control.)

I suggest using "#if" here for consistency.

[rkotlerimgtec, 2015/12/12 02:23:35]

Done.

+     return true;
+   #else
+     return false;
+   #endif
+   }
+
+   ...} // of BuildDefs

[Jim Stichnoth, 2015/12/12 00:04:34]

Might as well use the same comment style as in the code base:
  // end of namespace BuildDefs

[rkotlerimgtec, 2015/12/12 02:23:35]

Done.

+   } // end of Ice

[Jim Stichnoth, 2015/12/12 00:04:33]

Same here --
  // end of namespace Ice

[rkotlerimgtec, 2015/12/12 02:23:35]

Done.

+
+   Depending on whether the build system gives a value always to

[Jim Stichnoth, 2015/12/12 00:04:33]

Remove this paragraph if you agree with the corresponding 2 comments above.

[rkotlerimgtec, 2015/12/12 02:23:35]

Done.

+   FEATURE_SUPPORTED
+
+   And later in the code:
+
+   if (Ice::BuildDefs::hasFeature() {
+      ...
+   }
+
+   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.
+
+   \endverbatim **/
+
+
 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

[Jim Stichnoth, 2015/12/12 00:04:33]

Should "Return" be capitalized, here and below?

[rkotlerimgtec, 2015/12/12 02:23:35]

Done.

 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_MINIMUM is defined as a non-zero value

[Jim Stichnoth, 2015/12/12 00:04:34]

ALLOW_MINIMAL_BUILD

[rkotlerimgtec, 2015/12/12 02:23:35]

Done.

 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;
 #else  // !NDEBUG
   return true;
 #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;
 #else  // !PNACL_BROWSER_TRANSLATOR
   return false;
 #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;
 #else  // !ALLOW_EXTRA_VALIDATION
   return false;
 #endif // !ALLOW_EXTRA_VALIDATION
 }
 
 } // end of namespace BuildDefs
 } // end of namespace Ice
 
 #endif // SUBZERO_SRC_ICEBUILDDEFS_H