Properly document Clipboard code

src/core/clipboard/Clipboard.cpp

@@ -17,12 +17,6 @@ void Clipboard::put_persistent(std::string name, double value) {
     m_persistent_data[name] = value;
 }
 
-Objects* Clipboard::get(std::string name) {
-    if(m_data.count(name) == 0)
-        return NULL;
-    return m_data[name];
-}
-
 Objects* Clipboard::get(std::string name, std::string type) {
     if(m_data.count(name + type) == 0)
         return NULL;
@@ -44,7 +38,10 @@ void Clipboard::clear() {
     m_dataID.clear();
 }
 
-void Clipboard::checkCollections() {
-    for(auto& name : m_dataID)
-        LOG(DEBUG) << "Data held: " << name;
+std::vector<std::string> Clipboard::listCollections() {
+    std::vector<std::string> collections;
+    for(auto& name : m_dataID) {
+        collections.push_back(name);
+    }
+    return collections;
 }

src/core/clipboard/Clipboard.hpp

-#ifndef CLIPBOARD_H
-#define CLIPBOARD_H 1
+/**
+ * @file
+ * @brief Store objects for exachange between modules on the clipboard
+ * @copyright Copyright (c) 2017 CERN and the Allpix Squared authors.
+ * This software is distributed under the terms of the MIT License, copied verbatim in the file "LICENSE.md".
+ * In applying this license, CERN does not waive the privileges and immunities granted to it by virtue of its status as an
+ * Intergovernmental Organization or submit itself to any jurisdiction.
+ */
+
+#ifndef CORRYVRECKAN_CLIPBOARD_H
+#define CORRYVRECKAN_CLIPBOARD_H
 
-// Include files
 #include <iostream>
 #include <map>
 #include <string>
@@ -9,45 +17,88 @@
 #include "core/utils/log.h"
 #include "objects/Object.hpp"
 
-//-------------------------------------------------------------------------------
-// The Clipboard class is used to transfer information between modules during
-// the event processing. Any object inheriting from Object can be placed
-// on the clipboard, and retrieved by its name. At the end of each event, the
-// clipboard is wiped clean.
-//-------------------------------------------------------------------------------
-
 namespace corryvreckan {
 
+    /**
+     * @brief Class for temporary data storage for exachange between modules
+     *
+     * The Clipboard class is used to transfer information between modules during the event processing. \ref Objects can be
+     * placed on the clipboard, and retrieved by their name. At the end of each event, the clipboard is
+     * wiped clean.
+     *
+     * In addition, a permanent clipboard storage area for variables of type double is provided, which allow to exchange
+     * information which should outlast a single event. This is dubbed the "persistent storage"
+     */
     class Clipboard {
 
     public:
-        // Constructors and destructors
+        /**
+         * @brief Construct the clipboard
+         */
         Clipboard() {}
+        /**
+         * @brief Required virtual destructor
+         */
         virtual ~Clipboard() {}
 
-        // Add objects to clipboard - with name or name + type
+        /**
+         * @brief Add object to the clipboard
+         * @param name Name of the collection to be stored
+         * @param objects vector of Objects to store
+         */
         void put(std::string name, Objects* objects);
+
+        /**
+         * @brief Add object to the clipboard
+         * @param name Name of the collection to be stored
+         * @param type Type of the object collection to be stored
+         * @param Objects vector of Objects to store
+         */
         void put(std::string name, std::string type, Objects* objects);
-        void put_persistent(std::string name, double value);
 
-        // Get objects from clipboard - with name or name + type
-        Objects* get(std::string name);
-        Objects* get(std::string name, std::string type);
+        /**
+         * @brief Retrieve objects from the clipboard
+         * @param name Name of the object collection to fetch
+         * @param type Type of objects to be retrieved
+         * @return Vector of Object pointers
+         */
+        Objects* get(std::string name, std::string type = "");
 
+        /**
+         * @brief Store or update variable on the persistent clipboard storage
+         * @param name Name of the variable
+         * @param value Value to be stored
+         */
+        void put_persistent(std::string name, double value);
+
+        /**
+         * @brief Retrieve variable from the persistent clipboard storage
+         * @param name Name of the variable
+         * @return Stored value from the persistent clipboard storage
+         */
         double get_persistent(std::string name);
 
-        // Clear items on the clipboard
+        /**
+         * @brief Clear the event storage of the clipboard
+         */
         void clear();
 
-        // Quick function to check what is currently held by the clipboard
-        void checkCollections();
+        /**
+         * @brief Get a list of currently held collections on the clipboard event storage
+         * @return Vector of collections names currently stored on the clipboard
+         */
+        std::vector<std::string> listCollections();
 
     private:
         // Container for data, list of all data held
         std::map<std::string, Objects*> m_data;
+
+        // List of available data collections
         std::vector<std::string> m_dataID;
+
+        // Persistent clipboard storage
         std::map<std::string, double> m_persistent_data;
     };
 } // namespace corryvreckan
 
-#endif // CLIPBOARD_H
+#endif // CORRYVRECKAN_CLIPBOARD_H

src/objects/Object.hpp

-#ifndef CORRYVRECKANOBJECT_H
-#define CORRYVRECKANOBJECT_H 1
+/**
+ * @file
+ * @brief Definition of Object base class
+ * @copyright Copyright (c) 2017 CERN and the Allpix Squared authors.
+ * This software is distributed under the terms of the MIT License, copied verbatim in the file "LICENSE.md".
+ * In applying this license, CERN does not waive the privileges and immunities granted to it by virtue of its status as an
+ * Intergovernmental Organization or submit itself to any jurisdiction.
+ */
+
+/**
+ * @defgroup Objects Objects
+ * @brief Collection of objects passed around between modules
+ */
+
+#ifndef CORRYVRECKAN_OBJECT_H
+#define CORRYVRECKAN_OBJECT_H
 
-// Include files
 #include <string>
 #include <vector>
 #include "TObject.h"
 #include "TTree.h"
 
-//-------------------------------------------------------------------------------
-// Generic base class. Every class which inherits from Object can be
-// placed on the clipboard and written out to file.
-//-------------------------------------------------------------------------------
-
 namespace corryvreckan {
 
+    /**
+     * @ingroup Objects
+     * @brief Base class for internal objects
+     *
+     * Generic base class. Every class which inherits from Object can be placed on the clipboard and written out to file.
+    */
     class Object : public TObject {
 
     public:
@@ -53,4 +67,4 @@ namespace corryvreckan {
     typedef std::vector<Object*> Objects;
 } // namespace corryvreckan
 
-#endif // CORRYVRECKANOBJECT_H
+#endif // CORRYVRECKAN_OBJECT_H