Documentation only, no functional change

Added copyrights and comments within headers

Resolves openbmc/openbmc#959

Change-Id: If58d78a39fb08251a34a88c2b6340c9fa33d2569
Signed-off-by: Matthew Barth <msbarth@us.ibm.com>

7 files changed, 159 insertions, 3 deletions

diff --git a/fan_enclosure.cpp b/fan_enclosure.cpp
index aaf415d..b015ac6 100644
--- a/fan_enclosure.cpp
+++ b/fan_enclosure.cpp
@@ -1,3 +1,18 @@
+/**
+ * Copyright © 2017 IBM Corporation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
 #include <algorithm>
 #include <phosphor-logging/log.hpp>
 #include "fan_enclosure.hpp"
diff --git a/fan_enclosure.hpp b/fan_enclosure.hpp
index da6f7e5..1c8d241 100644
--- a/fan_enclosure.hpp
+++ b/fan_enclosure.hpp
@@ -12,6 +12,9 @@ namespace fan
 namespace presence
 {
 
+/**
+ * @brief Specifies the defined presence states of a fan enclosure
+ */
 typedef enum presenceState
 {
     NOT_PRESENT,
@@ -19,6 +22,13 @@ typedef enum presenceState
     UNKNOWN
 } presenceState;
 
+/**
+ * @class FanEnclosure
+ * @brief OpenBMC fan enclosure inventory presence implementation
+ * @details Inventory is based on the fan enclosure being present or not. This
+ * class represents that fan enclosure and updates its presences status within
+ * its inventory object based on the status of all its sensors.
+ */
 class FanEnclosure
 {
     using Property = std::string;
@@ -40,6 +50,12 @@ class FanEnclosure
         FanEnclosure& operator=(FanEnclosure&&) = delete;
         ~FanEnclosure() = default;
 
+        /**
+         * @brief Constructs Fan Enclosure Object
+         *
+         * @param[in] bus - Dbus bus object
+         * @param[in] fanProp - Fan enclosure properties
+         */
         FanEnclosure(sdbusplus::bus::bus& bus,
                      const phosphor::fan::Properties& fanProp) :
                         bus(bus),
@@ -50,20 +66,51 @@ class FanEnclosure
             updInventory();
         }
 
+        /**
+         * @brief Update inventory when the determined presence of this fan
+         * enclosure has changed
+         */
         void updInventory();
+        /**
+         * @brief Add a sensor association to this fan enclosure
+         *
+         * @param[in] sensor - Sensor associated to this fan enclosure
+         */
         void addSensor(
             std::unique_ptr<Sensor>&& sensor);
 
     private:
+        /** @brief Connection for sdbusplus bus */
         sdbusplus::bus::bus& bus;
+        /** @brief Inventory path for this fan enclosure */
         const std::string invPath;
+        /** @brief Description used as 'PrettyName' on inventory object */
         const std::string fanDesc;
+        /** @brief List of sensors associated with this fan enclosure */
         std::vector<std::unique_ptr<Sensor>> sensors;
+        /** @brief Last known presence state of this fan enclosure */
         presenceState presState = UNKNOWN;
 
+        /**
+         * @brief Get the current presence state based on all sensors
+         *
+         * @return Current presence state determined from all sensors
+         */
         presenceState getCurPresState();
         //TODO openbmc/openbmc#1299 - Move getInvService() to a utility file
+        /**
+         * @brief Get the inventory service name from the mapper object
+         *
+         * @return The inventory manager service name
+         */
         std::string getInvService();
+        /**
+         * @brief Construct the inventory object map
+         *
+         * @param[in] Current presence state
+         *
+         * @return The inventory object map to update inventory
+         */
         ObjectMap getObjectMap(bool curPresState);
 
 };
diff --git a/fan_properties.hpp b/fan_properties.hpp
index 22d655a..296318d 100644
--- a/fan_properties.hpp
+++ b/fan_properties.hpp
@@ -10,6 +10,10 @@ namespace phosphor
 namespace fan
 {
 
+/**
+ * @brief Fan enclosure properties
+ * @details Contains the inventory path, description and list of sensors
+ */
 using Properties = std::tuple<std::string,
                               std::string,
                               std::vector<std::string>>;
diff --git a/sensor_base.hpp b/sensor_base.hpp
index 2dc2b8d..c206e70 100644
--- a/sensor_base.hpp
+++ b/sensor_base.hpp
@@ -8,7 +8,14 @@ namespace fan
 namespace presence
 {
 
+// Forward declare FanEnclosure
 class FanEnclosure;
+/**
+ * @class Sensor
+ * @brief Base sensor implementation to be extended
+ * @details A type of presence detection sensor would extend this to override
+ * how presences is determined by the fan enclosure containing that type
+ */
 class Sensor
 {
     public:
@@ -19,6 +26,12 @@ class Sensor
         Sensor& operator=(Sensor&&) = delete;
         virtual ~Sensor() = default;
 
+        /**
+         * @brief Constructs Sensor Object
+         *
+         * @param[in] id - ID name of this sensor
+         * @param[in] fanEnc - Reference to the fan enclosure with this sensor
+         */
         Sensor(const std::string& id,
                FanEnclosure& fanEnc) :
             id(id),
@@ -27,10 +40,16 @@ class Sensor
             //Nothing to do here
         }
 
+        /**
+         * @brief Presence function that must be implemented within the derived
+         * type of sensor's implementation on how presence is determined
+         */
         virtual bool isPresent() = 0;
 
     protected:
+        /** @brief ID name of this sensor */
         const std::string id;
+        /** @brief Reference to the fan enclosure containing this sensor */
         FanEnclosure& fanEnc;
 
 };
diff --git a/tach_detect.cpp b/tach_detect.cpp
index 5da1b48..2449f82 100644
--- a/tach_detect.cpp
+++ b/tach_detect.cpp
@@ -1,3 +1,18 @@
+/**
+ * Copyright © 2017 IBM Corporation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
 #include <vector>
 #include <sdbusplus/bus.hpp>
 #include "fan_enclosure.hpp"
diff --git a/tach_sensor.cpp b/tach_sensor.cpp
index 91e249d..c21478b 100644
--- a/tach_sensor.cpp
+++ b/tach_sensor.cpp
@@ -1,3 +1,18 @@
+/**
+ * Copyright © 2017 IBM Corporation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
 #include <sdbusplus/exception.hpp>
 #include "tach_sensor.hpp"
 #include "fan_enclosure.hpp"
diff --git a/tach_sensor.hpp b/tach_sensor.hpp
index b9ac9b3..90d955b 100644
--- a/tach_sensor.hpp
+++ b/tach_sensor.hpp
@@ -12,6 +12,12 @@ namespace fan
 namespace presence
 {
 
+/**
+ * @class TachSensor
+ * @brief OpenBMC Tach feedback sensor presence implementation
+ * @details Derived sensor type that uses the tach feedback value to determine
+ * the presence of the fan enclosure that contains this sensor
+ */
 class TachSensor : public Sensor
 {
     public:
@@ -22,6 +28,13 @@ class TachSensor : public Sensor
         TachSensor& operator=(TachSensor&&) = delete;
         ~TachSensor() = default;
 
+        /**
+         * @brief Constructs Tach Sensor Object
+         *
+         * @param[in] bus - Dbus bus object
+         * @param[in] id - ID name of this sensor
+         * @param[in] fanEnc - Reference to the fan enclosure with this sensor
+         */
         TachSensor(
             sdbusplus::bus::bus& bus,
             const std::string& id,
@@ -36,14 +49,29 @@ class TachSensor : public Sensor
             // Nothing to do here
         }
 
+        /**
+         * @brief Determine the presence of this sensor using the tach feedback
+         *
+         * @return Presence state based on tach feedback
+         */
         bool isPresent();
 
     private:
+        /** @brief Connection for sdbusplus bus */
         sdbusplus::bus::bus& bus;
+        /** @brief Used to subscribe to dbus signals */
         sdbusplus::server::match::match tachSignal;
+        /** @brief Tach speed value given from the signal */
         int64_t tach = 0;
 
-        static std::string match(std::string id)
+        /**
+         * @brief Appends the fan sensor id to construct a match string
+         *
+         * @param[in] id - Fan sensor id
+         *
+         * @return Match string to register signal for the fan sensor id
+         */
+        static std::string match(const std::string& id)
         {
             return std::string("type='signal',"
                                "interface='org.freedesktop.DBus.Properties',"
@@ -51,11 +79,24 @@ class TachSensor : public Sensor
                                "path='/xyz/openbmc_project/sensors/fan_tach/" +
                                id + "'");
         }
-        // Tach signal callback handler
+        /**
+         * @brief Callback function on tach change signals
+         *
+         * @param[out] msg - Data associated with the subscribed signal
+         * @param[out] data - Pointer to this tach sensor object instance
+         * @param[out] err - Contains any sdbus error reference if occurred
+         *
+         * @return 0
+         */
         static int handleTachChangeSignal(sd_bus_message* msg,
                                           void* data,
                                           sd_bus_error* err);
-
+        /**
+         * @brief Determine & handle when the signal was a tach change
+         *
+         * @param[in] msg - Expanded sdbusplus message data
+         * @param[in] err - Contains any sdbus error reference if occurred
+         */
         void handleTachChange(sdbusplus::message::message& msg,
                               sd_bus_error* err);