From a4f1799470dac9e893acd3822eadb3162ff928f9 Mon Sep 17 00:00:00 2001
From: Ewan Barr <ewan.d.barr@googlemail.com>
Date: Sun, 30 Jul 2017 20:02:26 +0200
Subject: [PATCH] added docstrings throughout

---
 psrdada_cpp/cli_utils.hpp           | 19 ++++++++
 psrdada_cpp/dada_client_base.hpp    | 22 +++++++++
 psrdada_cpp/dada_dbnull.hpp         | 36 ++++++++++++++
 psrdada_cpp/dada_io_loop.hpp        | 15 ++++++
 psrdada_cpp/dada_io_loop_reader.hpp | 10 ++++
 psrdada_cpp/dada_io_loop_writer.hpp | 10 ++++
 psrdada_cpp/dada_junkdb.hpp         | 35 +++++++++++++
 psrdada_cpp/dada_read_client.hpp    | 76 +++++++++++++++++++++++++++++
 psrdada_cpp/dada_write_client.hpp   | 73 +++++++++++++++++++++++++++
 psrdada_cpp/examples/dbnull.cpp     |  9 ++++
 psrdada_cpp/examples/junkdb.cpp     |  9 ++++
 psrdada_cpp/multilog.hpp            | 22 +++++++++
 psrdada_cpp/raw_bytes.hpp           | 38 +++++++++++++++
 13 files changed, 374 insertions(+)

diff --git a/psrdada_cpp/cli_utils.hpp b/psrdada_cpp/cli_utils.hpp
index 5ac02413..5ac4c8ff 100644
--- a/psrdada_cpp/cli_utils.hpp
+++ b/psrdada_cpp/cli_utils.hpp
@@ -5,7 +5,26 @@
 
 namespace psrdada_cpp {
 
+    /**
+     * @brief      Convert a string into a shared memory key
+     *
+     * @param      in    A hexadecimal string (e.g. "dada")
+     *
+     * @note       No error checking is performed on the conversion, meaning
+     *             that non-hex valiues will still give an output (e.g. an input
+     *             of "dag" will drop the non-hex "g" character giving an output
+     *             of 0xda)
+     *
+     * @return     A key_t representation of the hexadecimal string
+     */
     key_t string_to_key(std::string const& in);
+
+    /**
+     * @brief      Sets the log level for boost logging.
+     *
+     * @param[in]  level  The desired log level as a string
+     *                    [debug, info, warning, error].
+     */
     void set_log_level(std::string level);
 
 } //namespace
diff --git a/psrdada_cpp/dada_client_base.hpp b/psrdada_cpp/dada_client_base.hpp
index e990ef74..1edf3f7d 100644
--- a/psrdada_cpp/dada_client_base.hpp
+++ b/psrdada_cpp/dada_client_base.hpp
@@ -17,12 +17,34 @@ namespace psrdada_cpp {
         MultiLog& _log;
 
     public:
+        /**
+         * @brief      Create a new basic DADA client instance
+         *
+         * @param[in]  key   The hexidecimal shared memory key
+         * @param      log   A MultiLog instance for logging buffer transactions
+         */
         DadaClientBase(key_t key, MultiLog& log);
         DadaClientBase(DadaClientBase const&) = delete;
         ~DadaClientBase();
+
+        /**
+         * @brief      Get the sizes of each data block in the ring buffer
+         */
         std::size_t data_buffer_size();
+
+        /**
+         * @brief      Get the sizes of each header block in the ring buffer
+         */
         std::size_t header_buffer_size();
+
+        /**
+         * @brief      Get the number of data blocks in the ring buffer
+         */
         std::size_t data_buffer_count();
+
+        /**
+         * @brief      Get the number of header blocks in the ring buffer
+         */
         std::size_t header_buffer_count();
 
     private:
diff --git a/psrdada_cpp/dada_dbnull.hpp b/psrdada_cpp/dada_dbnull.hpp
index 80adf5e3..8529b60b 100644
--- a/psrdada_cpp/dada_dbnull.hpp
+++ b/psrdada_cpp/dada_dbnull.hpp
@@ -8,6 +8,14 @@
 
 namespace psrdada_cpp
 {
+    /**
+     * @brief      Class for reading from a DADA buffer
+     *             and doing nothing with the data.
+     *
+     * @detail     This class is intended as both an example
+     *             for how to use CRTP with DadaIoLoopReader
+     *             and as a tool for testing.
+     */
     class DbNull
     : public DadaIoLoopReader<DbNull>
     {
@@ -16,9 +24,37 @@ namespace psrdada_cpp
         bool _infinite;
 
     public:
+        /**
+         * @brief      Create a new instance
+         *
+         * @param[in]  key     The shared memory key
+         * @param      log     A MultiLog instance
+         * @param[in]  nbytes  The number of bytes to read from the buffer.
+         *                     Setting this value to 0 will cause the instance
+         *                     to read forever.
+         */
         DbNull(key_t key, MultiLog& log, std::size_t nbytes);
         ~DbNull();
+
+        /**
+         * @brief      A callback to be called on connection
+         *             to a ring buffer.
+         *
+         * @detail     The first available header block in the
+         *             in the ring buffer is provided as an argument.
+         *             It is here that header parameters could be read
+         *             if desired.
+         *
+         * @param      block  A RawBytes object wrapping a DADA header buffer
+         */
         void on_connect(RawBytes& block);
+
+        /**
+         * @brief      A callback to be called on acqusition of a new
+         *             data block.
+         *
+         * @param      block  A RawBytes object wrapping a DADA data buffer
+         */
         void on_next(RawBytes& block);
     };
 
diff --git a/psrdada_cpp/dada_io_loop.hpp b/psrdada_cpp/dada_io_loop.hpp
index ac08269b..307fcb82 100644
--- a/psrdada_cpp/dada_io_loop.hpp
+++ b/psrdada_cpp/dada_io_loop.hpp
@@ -16,10 +16,25 @@ namespace psrdada_cpp
         bool _running;
 
     public:
+
+        /**
+         * @brief      Create new instance
+         *
+         * @param[in]  key   A hexadecimal shared memory key
+         * @param      log   A MultiLog instance
+         */
         DadaIoLoop(key_t key, MultiLog& log);
         DadaIoLoop(DadaIoLoop const&) = delete;
         ~DadaIoLoop();
+
+        /**
+         * @brief      Stop the IO loop processing
+         */
         void stop();
+
+        /**
+         * @brief      Start the IO loop processing
+         */
         virtual void run()=0;
     };
 
diff --git a/psrdada_cpp/dada_io_loop_reader.hpp b/psrdada_cpp/dada_io_loop_reader.hpp
index ccfb6330..7f443dfb 100644
--- a/psrdada_cpp/dada_io_loop_reader.hpp
+++ b/psrdada_cpp/dada_io_loop_reader.hpp
@@ -11,8 +11,18 @@ namespace psrdada_cpp
     class DadaIoLoopReader: public DadaIoLoop
     {
     public:
+        /**
+         * @brief      Create a IO loop for reading from a DADA buffer
+         *
+         * @param[in]  key   The hexidecimal shared memory key
+         * @param      log   A MultiLog instance for logging buffer transactions
+         */
         DadaIoLoopReader(key_t key, MultiLog& log);
         ~DadaIoLoopReader();
+
+        /**
+         * @brief      Start the IO loop processing
+         */
         void run();
     };
 } //namespace psrdada_cpp
diff --git a/psrdada_cpp/dada_io_loop_writer.hpp b/psrdada_cpp/dada_io_loop_writer.hpp
index 905813c0..8673637b 100644
--- a/psrdada_cpp/dada_io_loop_writer.hpp
+++ b/psrdada_cpp/dada_io_loop_writer.hpp
@@ -11,8 +11,18 @@ namespace psrdada_cpp
     class DadaIoLoopWriter: public DadaIoLoop
     {
     public:
+        /**
+         * @brief      Create a IO loop for writing to a DADA buffer
+         *
+         * @param[in]  key   The hexidecimal shared memory key
+         * @param      log   A MultiLog instance for logging buffer transactions
+         */
         DadaIoLoopWriter(key_t key, MultiLog& log);
         ~DadaIoLoopWriter();
+
+        /**
+         * @brief      Start the IO loop processing
+         */
         void run();
     };
 } //namespace psrdada_cpp
diff --git a/psrdada_cpp/dada_junkdb.hpp b/psrdada_cpp/dada_junkdb.hpp
index 62ab8ba6..b665ce57 100644
--- a/psrdada_cpp/dada_junkdb.hpp
+++ b/psrdada_cpp/dada_junkdb.hpp
@@ -8,6 +8,13 @@
 
 namespace psrdada_cpp
 {
+    /**
+     * @brief      Class for writing junk to a dada buffer
+     *
+     * @detail     This class is intended as both an example
+     *             for how to use CRTP with DadaIoLoopWriter
+     *             and as a tool for testing.
+     */
     class JunkDb
     : public DadaIoLoopWriter<JunkDb>
     {
@@ -16,9 +23,37 @@ namespace psrdada_cpp
         bool _infinite;
 
     public:
+        /**
+         * @brief      Create a new instance
+         *
+         * @param[in]  key     The shared memory key
+         * @param      log     A MultiLog instance
+         * @param[in]  nbytes  The number of bytes to write to the buffer.
+         *                     Setting this value to 0 will cause the instance
+         *                     to write forever.
+         */
         JunkDb(key_t key, MultiLog& log, std::size_t nbytes);
         ~JunkDb();
+
+        /**
+         * @brief      A callback to be called on connection
+         *             to a ring buffer.
+         *
+         * @detail     The first available header block in the
+         *             in the ring buffer is provided as an argument.
+         *             It is here that header parameters could be written
+         *             to if desired.
+         *
+         * @param      block  A RawBytes object wrapping a DADA header buffer
+         */
         void on_connect(RawBytes& block);
+
+        /**
+         * @brief      A callback to be called on acqusition of a new
+         *             data block.
+         *
+         * @param      block  A RawBytes object wrapping a DADA data buffer
+         */
         bool on_next(RawBytes& block);
     };
 
diff --git a/psrdada_cpp/dada_read_client.hpp b/psrdada_cpp/dada_read_client.hpp
index d17b329c..7bae5305 100644
--- a/psrdada_cpp/dada_read_client.hpp
+++ b/psrdada_cpp/dada_read_client.hpp
@@ -7,6 +7,10 @@
 
 namespace psrdada_cpp {
 
+    /**
+     * @brief      Class that provides means for reading from
+     *             a DADA ring buffer
+     */
     class DadaReadClient: public DadaClientBase
     {
     public:
@@ -17,11 +21,36 @@ namespace psrdada_cpp {
             std::unique_ptr<RawBytes> _current_block;
 
         public:
+            /**
+             * @brief      Create a new instance
+             *
+             * @param      parent  A reference to the parent reading client
+             */
             HeaderStream(DadaReadClient& parent);
             HeaderStream(HeaderStream const&) = delete;
             ~HeaderStream();
+
+            /**
+             * @brief      Get the next header block in the ring buffer
+             *
+             * @detail     As only one block can be open at a time, release() must
+             *             be called between subsequenct next() calls.
+             *
+             * @return     A RawBytes instance wrapping a pointer to share memory
+             */
             RawBytes& next();
+
+            /**
+             * @brief      Release the current data block.
+             *
+             * @detail     This will mark the block as cleared, making it
+             *             writeable by writing client.
+             */
             void release();
+
+            /**
+             * @brief      Check if we have read the last header block in buffer.
+             */
             bool at_end() const;
         };
 
@@ -33,12 +62,41 @@ namespace psrdada_cpp {
             std::size_t _block_idx;
 
         public:
+            /**
+             * @brief      Create a new instance
+             *
+             * @param      parent  A reference to the parent reading client
+             */
             DataStream(DadaReadClient& parent);
             DataStream(DataStream const&) = delete;
             ~DataStream();
+
+            /**
+             * @brief      Get the next data block in the ring buffer
+             *
+             * @detail     As only one block can be open at a time, release() must
+             *             be called between subsequenct next() calls.
+             *
+             * @return     A RawBytes instance wrapping a pointer to share memory
+             */
             RawBytes& next();
+
+            /**
+             * @brief      Release the current data block.
+             *
+             * @detail     This will mark the block as cleared, making it
+             *             writeable by writing client.
+             */
             void release();
+
+            /**
+             * @brief      Check if we have read the last data block in buffer.
+             */
             bool at_end() const;
+
+            /**
+             * @brief      Return the index of the currently open block
+             */
             std::size_t block_idx() const;
         };
 
@@ -48,10 +106,28 @@ namespace psrdada_cpp {
         DataStream _data_stream;
 
     public:
+        /**
+         * @brief      Create a new client for reading from a DADA buffer
+         *
+         * @param[in]  key   The hexidecimal shared memory key
+         * @param      log   A MultiLog instance for logging buffer transactions
+         */
         DadaReadClient(key_t key, MultiLog& log);
         DadaReadClient(DadaReadClient const&) = delete;
         ~DadaReadClient();
+
+        /**
+         * @brief      Get a reference to a header stream manager
+         *
+         * @return     A HeaderStream manager object for the current buffer
+         */
         HeaderStream& header_stream();
+
+        /**
+         * @brief      Get a reference to a data stream manager
+         *
+         * @return     A DataStream manager object for the current buffer
+         */
         DataStream& data_stream();
 
     private:
diff --git a/psrdada_cpp/dada_write_client.hpp b/psrdada_cpp/dada_write_client.hpp
index ddfb61a0..a9ecdf39 100644
--- a/psrdada_cpp/dada_write_client.hpp
+++ b/psrdada_cpp/dada_write_client.hpp
@@ -7,9 +7,18 @@
 
 namespace psrdada_cpp {
 
+    /**
+     * @brief      Class that provides means for writing to
+     *             a DADA ring buffer
+     */
     class DadaWriteClient: public DadaClientBase
     {
     public:
+
+        /**
+         * @brief      A helper class for encapsulating
+         *             the DADA buffer header blocks.
+         */
         class HeaderStream
         {
         private:
@@ -17,10 +26,31 @@ namespace psrdada_cpp {
             std::unique_ptr<RawBytes> _current_block;
 
         public:
+            /**
+             * @brief      Create a new instance
+             *
+             * @param      parent  A reference to the parent writing client
+             */
             HeaderStream(DadaWriteClient& parent);
             HeaderStream(HeaderStream const&) = delete;
             ~HeaderStream();
+
+            /**
+             * @brief      Get the next header block in the ring buffer
+             *
+             * @detail     As only one block can be open at a time, release() must
+             *             be called between subsequenct next() calls.
+             *
+             * @return     A RawBytes instance wrapping a pointer to share memory
+             */
             RawBytes& next();
+
+            /**
+             * @brief      Release the current header block.
+             *
+             * @detail     This will mark the block as filled, making it
+             *             readable by reading client.
+             */
             void release();
         };
 
@@ -32,19 +62,62 @@ namespace psrdada_cpp {
             std::size_t _block_idx;
 
         public:
+            /**
+             * @brief      Create a new instance
+             *
+             * @param      parent  A reference to the parent writing client
+             */
             DataStream(DadaWriteClient& parent);
             DataStream(DataStream const&) = delete;
             ~DataStream();
+
+            /**
+             * @brief      Get the next data block in the ring buffer
+             *
+             * @detail     As only one block can be open at a time, release() must
+             *             be called between subsequenct next() calls.
+             *
+             * @return     A RawBytes instance wrapping a pointer to share memory
+             */
             RawBytes& next();
+
+            /**
+             * @brief      Release the current data block.
+             *
+             * @detail     This will mark the block as filled, making it
+             *             readable by reading client.
+             */
             void release(bool eod=false);
+
+            /**
+             * @brief      Return the index of the currently open block
+             */
             std::size_t block_idx() const;
         };
 
     public:
+        /**
+         * @brief      Create a new client for writing to a DADA buffer
+         *
+         * @param[in]  key   The hexidecimal shared memory key
+         * @param      log   A MultiLog instance for logging buffer transactions
+         */
         DadaWriteClient(key_t key, MultiLog& log);
         DadaWriteClient(DadaWriteClient const&) = delete;
         ~DadaWriteClient();
+
+        /**
+         * @brief      Get a reference to a header stream manager
+         *
+         * @return     A HeaderStream manager object for the current buffer
+         */
         HeaderStream& header_stream();
+
+        /**
+         * @brief      Get a reference to a data stream manager
+         *
+         * @return     A DataStream manager object for the current buffer
+         */
         DataStream& data_stream();
 
     private:
diff --git a/psrdada_cpp/examples/dbnull.cpp b/psrdada_cpp/examples/dbnull.cpp
index 40bffb81..b438cbb3 100644
--- a/psrdada_cpp/examples/dbnull.cpp
+++ b/psrdada_cpp/examples/dbnull.cpp
@@ -70,9 +70,18 @@ int main(int argc, char** argv)
             std::cerr << desc << std::endl;
             return ERROR_IN_COMMAND_LINE;
         }
+
+        /**
+         * All the application code goes here
+         */
+
         MultiLog log("dbnull");
         DbNull proc(key, log, nbytes);
         proc.run();
+
+        /**
+         * End of application code
+         */
     }
     catch(std::exception& e)
     {
diff --git a/psrdada_cpp/examples/junkdb.cpp b/psrdada_cpp/examples/junkdb.cpp
index 1d165690..f9f22743 100644
--- a/psrdada_cpp/examples/junkdb.cpp
+++ b/psrdada_cpp/examples/junkdb.cpp
@@ -69,9 +69,18 @@ int main(int argc, char** argv)
             std::cerr << desc << std::endl;
             return ERROR_IN_COMMAND_LINE;
         }
+
+        /**
+         * All the application code goes here
+         */
+
         MultiLog log("junkdb");
         JunkDb proc(key, log, nbytes);
         proc.run();
+
+        /**
+         * End of application code
+         */
     }
     catch(std::exception& e)
     {
diff --git a/psrdada_cpp/multilog.hpp b/psrdada_cpp/multilog.hpp
index 707a78af..7fbece1f 100644
--- a/psrdada_cpp/multilog.hpp
+++ b/psrdada_cpp/multilog.hpp
@@ -6,6 +6,11 @@
 
 namespace psrdada_cpp {
 
+    /**
+     * @brief      A class for wrapping multilog_t instances
+     *             required for logging with the underlying
+     *             DADA API.
+     */
     class MultiLog
     {
     private:
@@ -14,12 +19,29 @@ namespace psrdada_cpp {
         bool _open;
 
     public:
+        /**
+         * @brief      Create a new instance
+         *
+         * @param[in]  name  The name to give this logger
+         */
         explicit MultiLog(std::string name);
         MultiLog(MultiLog const&) = delete;
         ~MultiLog();
 
+        /**
+         * @brief      Get a native handle to the wrapped multilog_t pointer
+         */
         multilog_t* native_handle();
 
+        /**
+         * @brief      Write to the log
+         *
+         * @param[in]  priority   The priority (0, 1, 2...)
+         * @param[in]  format     The format string
+         * @param[in]  ...        Parameters for the format string
+         *
+         * @tparam     Args       The types of the parameters for the format string
+         */
         template<class... Args>
         void write(int priority, const char* format, Args&&... args);
 
diff --git a/psrdada_cpp/raw_bytes.hpp b/psrdada_cpp/raw_bytes.hpp
index 3fed09bf..76bd32eb 100644
--- a/psrdada_cpp/raw_bytes.hpp
+++ b/psrdada_cpp/raw_bytes.hpp
@@ -5,6 +5,17 @@
 
 namespace psrdada_cpp {
 
+    /**
+     * @brief      Class for wrapping a raw pointer to a buffer of shared memory
+     *
+     * @detail     This class is used to wrap pointers to shared memory
+     *             returned by calls to the lower-level DADA API.
+     *
+     *             This class is used to wrap buffers acquired by both reading
+     *             and writing clients. For writing clients, it is necessary to
+     *             set the number of bytes written using the used_bytes() method
+     *             after writing. This value is used when releasing the buffer.
+     */
     class RawBytes
     {
     private:
@@ -13,12 +24,39 @@ namespace psrdada_cpp {
         std::size_t _used_bytes;
 
     public:
+        /**
+         * @brief      Create a new RawBytes instance
+         *
+         * @param      ptr    The pointer to the buffer to wrap
+         * @param[in]  total  The total number of bytes in the buffer
+         * @param[in]  used   The number of bytes currently used in the buffer
+         */
         RawBytes(char* ptr, std::size_t total, std::size_t used=0);
         RawBytes(RawBytes const&) = delete;
         ~RawBytes();
+
+        /**
+         * @brief      Get the total number of bytes in the buffer
+         */
         std::size_t total_bytes();
+
+        /**
+         * @brief      Get the number of currently used bytes in the buffer
+         */
         std::size_t used_bytes();
+
+        /**
+         * @brief      Set the number of currently used bytes in the buffer
+         *
+         * @detail     For writing clients, this method should be called after
+         *             all writes are complete so that the number of used_bytes
+         *             can be passed to reading clients.
+         */
         void used_bytes(std::size_t);
+
+        /**
+         * @brief      Get a raw pointer to the start of the buffer
+         */
         char* ptr();
     };
 
-- 
GitLab