From cf5b171853de6146f451d8e08028088856d40394 Mon Sep 17 00:00:00 2001
From: albertoesmp <albertoesmp@gmail.com>
Date: Mon, 18 Sep 2023 21:03:05 +0200
Subject: [PATCH] Documented HDA_OfstreamWrapper

---
 src/dataanalytics/HDA_OfstreamWrapper.h | 38 +++++++++++++++++++++++--
 1 file changed, 36 insertions(+), 2 deletions(-)

diff --git a/src/dataanalytics/HDA_OfstreamWrapper.h b/src/dataanalytics/HDA_OfstreamWrapper.h
index bcec285d9..b9fb094d1 100644
--- a/src/dataanalytics/HDA_OfstreamWrapper.h
+++ b/src/dataanalytics/HDA_OfstreamWrapper.h
@@ -12,17 +12,32 @@ class HDA_OfstreamWrapper{
 protected:
     // ***  ATTRIBUTES  *** //
     // ******************** //
+    /**
+     * @brief The output file stream used to write to a file.
+     */
     std::ofstream ofs;
     /**
-     * @brief The separator between recorded elements
+     * @brief The separator between recorded elements.
      */
     std::string sep;
+    /**
+     * @brief Boolean flag to control whether the HDA_OfstreamWrapper has
+     *  written something or not. Once something has been written, the flag
+     *  will be set to true. By default, it is initialized to false.
+     */
     bool hasWrittenSomething;
 
 public:
     // ***  CONSTRUCTION / DESTRUCTION  *** //
     // ************************************ //
-    HDA_OfstreamWrapper(std::string const &outpath, std::string const &sep=",") :
+    /**
+     * @brief Build a HDA_OfstreamWrapper to handle writing records to files.
+     * @param outpath The path to the output file.
+     * @see HDA_OfstreamWrapper::sep
+     */
+    HDA_OfstreamWrapper(
+        std::string const &outpath, std::string const &sep=","
+    ) :
         ofs(outpath, std::ios_base::out),
         sep(sep),
         hasWrittenSomething(false)
@@ -31,11 +46,24 @@ class HDA_OfstreamWrapper{
 
     // ***  OUTPUT FILE STREAM METHODS  *** //
     // ************************************ //
+    /**
+     * @brief Wraps the is_open method of the output file stream class.
+     */
     inline bool is_open() {return ofs.is_open();}
+    /**
+     * @brief Wraps the close method of the output file stream class.
+     */
     inline void close() {return ofs.close();}
 
     // ***  OUTPUT FILE STREAM OPERATORS  *** //
     // ************************************** //
+    /**
+     * @brief Default stream input operator, i.e., <<.
+     * @tparam T The type of element to be written.
+     * @param elem The element to be written.
+     * @return A reference to the HDA_OfstreamWrapper itself for fluent
+     *  programming purposes.
+     */
     template <typename T>
     HDA_OfstreamWrapper & operator <<(T const &elem){
         if(hasWrittenSomething){
@@ -48,6 +76,12 @@ class HDA_OfstreamWrapper{
         return *this;
     }
 
+    /**
+     * @brief Stream input operator to handle vectors of doubles as element.
+     * @param elem The vector of doubles as element.
+     * @return A reference to the HDA_OfstreamWrapper itself for fluent
+     *  programming purposes.
+     */
     HDA_OfstreamWrapper & operator <<(std::vector<double> const &elem){
         ofs << elem[0];
         for(size_t i = 1 ; i < elem.size(); ++i){