Add doxygen fapi2 tooling, doc clean up

Change-Id: Ieb787904e7d359f966298cf834195bed5ce86207
Reviewed-on: http://gfw160.aus.stglabs.ibm.com:8080/gerrit/15730
Reviewed-by: Brian Silver <bsilver@us.ibm.com>
Tested-by: Brian Silver <bsilver@us.ibm.com>
Reviewed-on: http://gfw160.aus.stglabs.ibm.com:8080/gerrit/20119
Tested-by: Jenkins Server
Reviewed-by: Derk Rembold <rembold@de.ibm.com>

7 files changed, 70 insertions, 31 deletions

diff --git a/import/hwpf/fapi2/include/buffer.H b/import/hwpf/fapi2/include/buffer.H
index e8035984..6d891637 100644
--- a/import/hwpf/fapi2/include/buffer.H
+++ b/import/hwpf/fapi2/include/buffer.H
@@ -52,6 +52,7 @@ namespace fapi2
     class buffer : public buffer_base<T>
     {
     public:
+        /// Shortcut typedef to map to our traits class
         typedef typename buffer_base<T, buffer>::bits_type bits_type;
 
         ///
@@ -280,7 +281,7 @@ namespace fapi2
         /// @tparam L Length of bits to insert
         /// @tparam SS Start bit in source
         /// @tparam OT the type of the incoming (origin) data
-        /// @param[in] i_data OT value to copy into DataBuffer
+        /// @param[in] i_datain OT value to copy into DataBuffer
         ///    - data is taken left aligned
         /// @note Asserting that all the parameters are known at
         /// compile time so this can be templated only. If that is not
@@ -352,7 +353,7 @@ namespace fapi2
         /// @tparam SB Start bit to insert into
         /// @tparam L Length of bits to insert
         /// @tparam OT the type of the incoming (origin) data
-        /// @param[in] i_data OT value to copy into DataBuffer
+        /// @param[in] i_datain OT value to copy into DataBuffer
         ///    - data is taken right aligned
         /// @note Data is assumed to be aligned on the word boundary of L
         /// @note Asserting that all the parameters are known at
diff --git a/import/hwpf/fapi2/include/buffer_base.H b/import/hwpf/fapi2/include/buffer_base.H
index 73dc5156..c9f7e7e3 100644
--- a/import/hwpf/fapi2/include/buffer_base.H
+++ b/import/hwpf/fapi2/include/buffer_base.H
@@ -162,7 +162,9 @@ namespace fapi2
 
     public:
 
+        /// Shortcut typedef to get to our traits class
         typedef typename TT::bits_type bits_type;
+        /// Shortcut typedef to get to our traits class
         typedef typename TT::unit_type unit_type;
 
         ///
@@ -199,6 +201,11 @@ namespace fapi2
         /// @return The contents of the buffer
         ///
         inline T& operator()(void) { return iv_data; }
+
+        ///
+        /// @brief Get the contents of the buffer
+        /// @return Reference to the contents of the buffer
+        ///
         inline const T& operator()(void) const { return iv_data; }
 
         /// @name Buffer Manipulation Functions
@@ -295,6 +302,7 @@ namespace fapi2
         inline void clear(void)
             { TT::clear(iv_data); }
 
+        /// The contents of the buffer
         T iv_data;
     };
 
diff --git a/import/hwpf/fapi2/include/error_scope.H b/import/hwpf/fapi2/include/error_scope.H
index 53f9339d..d510c6de 100644
--- a/import/hwpf/fapi2/include/error_scope.H
+++ b/import/hwpf/fapi2/include/error_scope.H
@@ -70,7 +70,7 @@
 /// @brief Wrapper to check an operation for an error state
 /// and jump to the label cleam_up if there is an error.
 /// @param[in] __operation__ an operation which returns a fapi::ReturnCode
-/// @param[in] Optional vararg format/agruments for trace output.
+/// @param[in] ... vararg format/agruments for trace output (optional)
 /// @note This implementation does not support PIB error masks or
 /// FSP operational states.
 /// @warning The trace information is only going to be seen during
diff --git a/import/hwpf/fapi2/include/hw_access.H b/import/hwpf/fapi2/include/hw_access.H
index 3df8a710..dc372a38 100644
--- a/import/hwpf/fapi2/include/hw_access.H
+++ b/import/hwpf/fapi2/include/hw_access.H
@@ -47,8 +47,10 @@
 #include <fapiMultiScom.H>
 #endif
 
+/// @cond
 typedef uint64_t spyId_t;
 typedef uint64_t scanRingId_t;
+/// @endcond
 
 namespace fapi2
 {
@@ -125,14 +127,43 @@ namespace fapi2
     }
 
     //--------------------------------------------------------------------------
+    // Operational Mode Error Functions
+    //--------------------------------------------------------------------------
+
+    /// @enum OpModes operational Mode Error Functions
+    enum OpModes
+    {
+        // These are bit-masks in case they need to be or'd together
+        NORMAL           = 0x00,
+        IGNORE_HW_ERROR  = 0x01,
+        DO_NOT_DO_WAKEUP = 0x02,
+    };
+
+    /// @brief Sets the operational mode
+    /// @param[in]  i_mode     The new mode
+    void setOpMode(const OpModes i_mode)
+    {
+        // No-op for now. Should set thread-local operational mode
+        return;
+    }
+
+    /// @brief Gets the operational mode
+    /// @return the operational mode
+    OpModes getOpMode(void)
+    {
+        // No-op for now. Should read thread-local operational mode
+        return NORMAL;
+    }
+
+    //--------------------------------------------------------------------------
     // HW Communication Functions
     //--------------------------------------------------------------------------
 
     /// @brief Reads a SCOM register from a chip.
-    /// @Tparam K template parameter, passed in target.
+    /// @tparam K template parameter, passed in target.
     /// @param[in]  i_target     HW target to operate on.
     /// @param[in]  i_address    SCOM register address to read from.
-    /// @param[out] o_date       Buffer that holds data read from HW target.
+    /// @param[out] o_data       Buffer that holds data read from HW target.
     /// @return fapi::ReturnCode. FAPI2_RC_SUCCESS if success, else error code.
     template< TargetType K >
     ReturnCode getScom(const Target<K>& i_target, const uint64_t i_address,
@@ -395,7 +426,7 @@ namespace fapi2
     /// These spy access interfaces are only used in FSP and cronus
     /// HB does not allow spy access
 
-#if defined(FAPI_SUPPORT_SPY_AS_ENUM) || defined(FAPI_SUPPORT_SPY_AS_STRING)
+#if defined(FAPI_SUPPORT_SPY_AS_ENUM) || defined(FAPI_SUPPORT_SPY_AS_STRING) || defined(DOXYGEN)
     /// @brief Reads a spy from a chip.
     /// @tparam K template parameter, passed in target.
     /// @param[in]  i_target   Target to operate on.
@@ -442,7 +473,7 @@ namespace fapi2
 
 #ifdef FAPI_SUPPORT_SPY_AS_ENUM
 
-#ifndef DOCUMENTATION
+#ifndef DOXYGEN
 #define fapiGetSpy(TARGET, ID, DATA) \
     _fapiGetSpy(TARGET, FAPI_SPY_NAMES::ID.value, DATA )
 #endif
@@ -467,7 +498,7 @@ namespace fapi2
 
 #ifdef FAPI_SUPPORT_SPY_AS_STRING
 
-#ifndef DOCUMENTATION
+#ifndef DOXYGEN
 #define fapiGetSpy(TARGET, ID, DATA) _fapiGetSpy(TARGET, #ID, DATA)
 #endif
     template< TargetType K >
@@ -476,7 +507,7 @@ namespace fapi2
                            variable_buffer& o_data);
 #endif
 
-#if defined(FAPI_SUPPORT_SPY_AS_ENUM) || defined(FAPI_SUPPORT_SPY_AS_STRING)
+#if defined(FAPI_SUPPORT_SPY_AS_ENUM) || defined(FAPI_SUPPORT_SPY_AS_STRING) || defined(DOXYGEN)
     /// @brief Writes a spy on a chip.
     /// @tparam K template parameter, passed in target.
     /// @param[in]  i_target   Target to operate on.
@@ -519,7 +550,7 @@ namespace fapi2
 #endif
 
 #ifdef FAPI_SUPPORT_SPY_AS_ENUM
-#ifndef DOCUMENTATION
+#ifndef DOXYGEN
 #define fapiPutSpy(TARGET, ID, DATA) \
     _fapiPutSpy(TARGET, FAPI_SPY_NAMES::ID.value, DATA)
 #endif
@@ -540,7 +571,7 @@ namespace fapi2
 #endif
 
 #ifdef FAPI_SUPPORT_SPY_AS_STRING
-#ifndef DOCUMENTATION
+#ifndef DOXYGEN
 #define fapiPutSpy(TARGET, ID, DATA) _fapiPutSpy(TARGET, #ID, DATA)
 #endif
     template< TargetType K >
@@ -615,7 +646,7 @@ namespace fapi2
                                 variable_buffer& o_imageData);
 #endif
 
-#if defined(FAPI_SUPPORT_SPY_AS_ENUM) || defined(FAPI_SUPPORT_SPY_AS_STRING)
+#if defined(FAPI_SUPPORT_SPY_AS_ENUM) || defined(FAPI_SUPPORT_SPY_AS_STRING) || defined(DOXYGEN)
     /// @brief Reads spy data from a ring image buffer
     /// @param[in]   i_target      Target to operate on
     /// @param[in]   i_spyId       The spy's id
@@ -636,7 +667,7 @@ namespace fapi2
 #endif
 
 #ifdef FAPI_SUPPORT_SPY_AS_ENUM
-#ifndef DOCUMENTATION
+#ifndef DOXYGEN
 #define fapiGetSpyImage(TARGET, ID, DATA1, DATA2) \
     _fapiGetSpyImage(TARGET,                                            \
                      FAPI_SPY_NAMES::ID.value,                          \
@@ -651,7 +682,7 @@ namespace fapi2
 
 #ifdef FAPI_SUPPORT_SPY_AS_STRING
 // fapiGetSpyImage function Cronus version
-#ifndef DOCUMENTATION
+#ifndef DOXYGEN
 #define fapiGetSpyImage(TARGET, ID, DATA1, DATA2) \
     _fapiGetSpyImage(TARGET,                                            \
                      #ID, DATA1,DATA2)
@@ -663,7 +694,7 @@ namespace fapi2
                        const fapi::buffer<fapi::bits_container> & i_imageData);
 #endif
 
-#ifdef FAPI_SUPPORT_MULTI_SCOM
+#if defined(FAPI_SUPPORT_MULTI_SCOM) || defined(DOXYGEN)
 
     /// @brief Performs a multiple SCOM operation
     ///        This interface performs multiple SCOM operations on a chip in the
diff --git a/import/hwpf/fapi2/include/return_code.H b/import/hwpf/fapi2/include/return_code.H
index 5c891247..0442ca89 100644
--- a/import/hwpf/fapi2/include/return_code.H
+++ b/import/hwpf/fapi2/include/return_code.H
@@ -119,7 +119,7 @@ namespace fapi2
 
         ///
         /// @brief Constructor.
-        /// @param[in] The rc to set
+        /// @param[in] i_rc the rc to set
         ///
         ReturnCode(const uint64_t i_rc = FAPI2_RC_SUCCESS):
             iv_rc(i_rc)
@@ -168,13 +168,12 @@ namespace fapi2
         uint64_t iv_rc;
     };
 
-
     /// This implementation assumes no exception handling and leverages thread-local
     /// storage. For platforms without thread support, a global variable will
     /// suffice for the error state.
-    extern thread_local ReturnCode current_err;
-    extern thread_local uint64_t pib_error_mask;
-    extern thread_local uint64_t operational_state;
+    extern thread_local ReturnCode current_err;      /// the current error state
+    extern thread_local uint64_t pib_error_mask;     /// the pib mask
+    extern thread_local uint64_t operational_state;  /// the operational mode
 
 };
 
diff --git a/import/hwpf/fapi2/include/target.H b/import/hwpf/fapi2/include/target.H
index 0c43eebc..52b6a478 100644
--- a/import/hwpf/fapi2/include/target.H
+++ b/import/hwpf/fapi2/include/target.H
@@ -103,7 +103,7 @@ namespace fapi2
 
         ///
         /// @brief Create a Target, with a value
-        /// @param[in] V the value (i.e., specific element this
+        /// @param[in] Value the value (i.e., specific element this
         /// target represents, or pointer)
         /// @note Platforms can mangle the value and K to get a
         /// single uint64_t in value which represents all the information
@@ -226,8 +226,8 @@ namespace fapi2
     /// @brief Return the string interpretation of this target
     /// @tparam T The type of the target
     /// @tparam B The type of the buffer
-    /// @param[in] The Target<T>
-    /// @param[in] The buffer
+    /// @param[in] i_target Target<T>
+    /// @param[in] i_buffer buffer
     /// @return void
     /// @post The contents of the buffer is replaced with the string
     /// representation of the target
@@ -257,7 +257,7 @@ namespace fapi2
     ///
     /// @brief Get an enumerated target of a specific type
     /// @tparam T The type of the target
-    /// @param[in] uint64_t representing the ordinal number of
+    /// @param[in] Ordinal representing the ordinal number of
     /// the desired target
     /// @return Target<T> the target requested
     ///
@@ -292,8 +292,8 @@ namespace fapi2
     /// @brief Return the string interpretation of this target
     /// @tparam T The type of the target
     /// @tparam B The type of the buffer
-    /// @param[in] The Target<T>
-    /// @param[in] The buffer
+    /// @param[in] i_target Target<T>
+    /// @param[in] i_buffer buffer
     /// @return void
     /// @post The contents of the buffer is replaced with the string
     /// representation of the target
diff --git a/import/hwpf/fapi2/include/variable_buffer.H b/import/hwpf/fapi2/include/variable_buffer.H
index bf950f89..a1280830 100644
--- a/import/hwpf/fapi2/include/variable_buffer.H
+++ b/import/hwpf/fapi2/include/variable_buffer.H
@@ -34,6 +34,7 @@
 
 namespace fapi2
 {
+    /// @brief Get a 32 bit mask quickly
     // This is one of the main reasons we static_assert in the ctor's
     // to ensure the unit_type is 32 bits.
     inline uint32_t fast_mask32(int32_t i_pos, int32_t i_len)
@@ -71,7 +72,6 @@ namespace fapi2
     ///            incoming data
     /// @param[in] i_target_start_bit The starting bit position in this
     /// @param[in] i_length The length, in bits, the user wants copied.
-    /// @endcond
     ///
     template<typename unit_type, typename bits_type>
     inline fapi2::ReturnCode _insert(const unit_type* i_source,
@@ -154,6 +154,7 @@ namespace fapi2
 
         return fapi2::FAPI2_RC_SUCCESS;
     }
+    /// @endcond
 
     /// @brief Class representing a FAPI variable_buffer.
     /// @remark Variable buffers are buffers which can be variable in length
@@ -422,11 +423,11 @@ namespace fapi2
 
         ///
         /// @brief Copy in a right aligned (decimal) element
-        /// @param[in] i_data, the incoming data
+        /// @param[in] i_data the incoming data
         ///    - data is taken right aligned
         /// @param[in] i_targetStart The starting bit position in this
         ///            - Defaultst to 0
-        /// @param[in] i_length The length, in bits, the user wants copied.
+        /// @param[in] i_len The length, in bits, the user wants copied.
         ///            - Defaults to all of the bits in the source which fit
         /// @return FAPI2_RC_SUCCESS on success, FAPI2_RC_OVERFLOW otherwise
         ///
@@ -518,7 +519,7 @@ namespace fapi2
 
 
 
-
+    /// @cond
     //
     // Generic insert
     //
@@ -656,7 +657,6 @@ namespace fapi2
         bits_type i_offset);
 #endif
     /// @endcond
-
 };