Improve documentation

.github/workflows/build.yml

@@ -205,22 +205,20 @@ jobs:
         run: |
           sudo apt-get update
           sudo apt-get install -y doxygen=1.9.1-2ubuntu2
-          pip3 install 'exhale==0.3.6'
-          pip3 install 'sphinx==5.0.0'
-          pip3 install 'sphinx_rtd_theme==1.2.2'
+          pip3 install 'exhale==0.3.7'
+          pip3 install 'sphinx==7.3.7'
+          pip3 install 'sphinx_rtd_theme==2.0.0'
           pip3 install 'json2html==1.3.0'
 
       - name: Generate documentation for EDIE
         run: |
-          sphinx-build src/decoders/common/doc doc/decoders/common/doc/html
-          sphinx-build src/decoders/novatel/doc doc/decoders/novatel/doc/html
-          sphinx-build src/hw_interface/stream_interface/doc doc/hw_interface/stream_interface/doc/html
+          sphinx-build docs docs/build
           python3 scripts/database_to_html.py database/messages_public.json
 
       - name: Archive documentation artifacts
         uses: actions/[email protected]
         with:
           name: documentation
           path: |
-            doc
+            docs/build
             database/messages_public.html

.gitignore

@@ -1,7 +1,8 @@
-.vs/
+.vs/
 .vscode/
 .idea/
 build/
+docs/build
 bin/
 venv/
 CMakeSettings.json

README.md

@@ -23,6 +23,9 @@ Documentation on NovAtel's data (commands, logs, messages, and responses) can be
 
 ## Getting Started
 
+Regardless of your operating system, have [Conan](https://conan.io/) installed as a prerequisite. 
+Conan is a package manager for C++ and is used by EDIE.
+
 ### Building EDIE on Linux (Ubuntu 18.04 or newer)
 
 1. Open terminal

src/decoders/common/doc/conf.py → docs/conf.py

@@ -3,6 +3,8 @@
 # This file only contains a selection of the most common options. For a full
 # list see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
+# https://devblogs.microsoft.com/cppblog/clear-functional-c-documentation-with-sphinx-breathe-doxygen-cmake/
+# https://www.codingwiththomas.com/blog/my-sphinx-best-practice-for-a-multiversion-documentation-in-different-languages
 
 # -- Path setup --------------------------------------------------------------
 
@@ -18,8 +20,8 @@
 # -- Project information -----------------------------------------------------
 
 project = 'EDIE'
-copyright = '2020, rdoris'
-author = 'rdoris'
+copyright = '2024, NovAtel'
+author = 'NovAtel'
 
 
 # -- General configuration ---------------------------------------------------
@@ -44,7 +46,7 @@
 
 # -- Options for HTML output -------------------------------------------------
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
+# The theme to use for HTML and HTML Help pages. See the documentation for
 # a list of builtin themes.
 #
 html_theme = "sphinx_rtd_theme"
@@ -80,10 +82,10 @@
     # "treeViewIsBootstrap": True,
     "exhaleExecutesDoxygen": True,
     "exhaleDoxygenStdin":    textwrap.dedent('''
-      INPUT = ../api
-      EXCLUDE_PATTERNS       = */libgen/*
-      EXCLUDE_PATTERNS       += */nov-decoder/tests/*
-      EXCLUDE_PATTERNS       += */nov-decoder/lib/*
+      INPUT = ../src/decoders/common/api
+      INPUT += ../src/decoders/dynamic_library/api
+      INPUT += ../src/decoders/novatel/api
+      INPUT += ../src/hw_interface/dynamic_library/api
+      INPUT += ../src/hw_interface/stream_interface/api
     ''')
 }
-

src/decoders/novatel/doc/index.rst → docs/index.rst

@@ -3,7 +3,7 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to ToolsLib's documentation!
+Welcome to EDIE's documentation!
 ====================================
 
 .. toctree::
@@ -16,6 +16,3 @@ Indices and tables
 ==================
 
 * :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-

examples/novatel/converter_components/converter_components.cpp

@@ -179,7 +179,7 @@ int main(int argc, char* argv[])
                 pucFrameBuffer[stMetaData.uiLength] = '\0';
                 pclLogger->info("Framed: {}", reinterpret_cast<char*>(pucFrameBuffer));
 
-                // Decode the header.  Get metadata here and populate the Intermediate header.
+                // Decode the header. Get metadata here and populate the Intermediate header.
                 eDecoderStatus = clHeaderDecoder.Decode(pucFrameBuffer, stHeader, stMetaData);
 
                 if (eDecoderStatus == STATUS::SUCCESS)

examples/novatel/converter_file_parser/converter_file_parser.cpp

@@ -126,7 +126,7 @@ int main(int argc, char* argv[])
 
     if (!clFileParser.SetStream(&clIfs))
     {
-        pclLogger->error("Input stream could not be set.  The stream is either unavailable or exhausted.");
+        pclLogger->error("Input stream could not be set. The stream is either unavailable or exhausted.");
         exit(-1);
     }
 

examples/novatel/dynamic_components/dynamic_components.cpp

@@ -164,7 +164,7 @@ int main(int argc, char* argv[])
                 pucFrameBuffer[stMetaData.uiLength] = '\0';
                 pclLogger->info("Framed: {}", reinterpret_cast<char*>(pucFrameBuffer));
 
-                // Decode the header.  Get metadata here and populate the Intermediate header.
+                // Decode the header. Get metadata here and populate the Intermediate header.
                 eDecoderStatus = NovatelHeaderDecoderDecode(pclHeaderDecoder, pucFrameBuffer, &stHeader, &stMetaData);
 
                 if (eDecoderStatus == STATUS::SUCCESS)

examples/novatel/range_decompressor/range_decompressor.cpp

@@ -149,7 +149,7 @@ int main(int argc, char* argv[])
         eStatus = clFramer.GetFrame(pucReadBuffer, MAX_ASCII_MESSAGE_LENGTH, stMetaData);
         if (eStatus == STATUS::SUCCESS)
         {
-            // Decode the header.  Get metadata here and populate the Intermediate header.
+            // Decode the header. Get metadata here and populate the Intermediate header.
             eStatus = clHeaderDecoder.Decode(pucReadBuffer, stHeader, stMetaData);
             if (eStatus == STATUS::SUCCESS)
             {

src/decoders/common/api/circular_buffer.hpp

@@ -31,6 +31,7 @@
 
 //============================================================================
 //! \class CircularBuffer
+//! \brief Used for maintaining a continuous/rotating buffer of set capacity.
 //============================================================================
 class CircularBuffer
 {
@@ -64,29 +65,29 @@ class CircularBuffer
     void SetCapacity(uint32_t uiCapacity_);
 
     //----------------------------------------------------------------------------
-    //! \brief Returns current capacity of buffer.
+    //! \return current capacity of buffer.
     //----------------------------------------------------------------------------
     [[nodiscard]] inline uint32_t GetCapacity() const;
 
     //----------------------------------------------------------------------------
-    //! \brief Returns number of bytes of data in buffer. Number of bytes between
+    //! \return number of bytes of data in buffer. Number of bytes between
     //! beginning of buffer and write cursor.
     //----------------------------------------------------------------------------
     [[nodiscard]] inline uint32_t GetLength() const;
 
     //----------------------------------------------------------------------------
-    //! \brief Returns the current buffer.
+    //! \return the current buffer.
     //----------------------------------------------------------------------------
     [[nodiscard]] inline unsigned char* GetBuffer() const;
 
     //----------------------------------------------------------------------------
-    //! \brief Append data to end of buffer.  Will increase buffer size if needed.
+    //! \brief Append data to end of buffer. Will increase buffer size if needed.
     //
     //! \param[in] pucData_ unsigned char buffer pointer from which data to
     //! append to the queue.
     //! \param[in] uiBytes_ Size of data (in bytes) to append from above address.
     //
-    //! \return AReturn number of bytes actually appended
+    //! \return Number of bytes actually appended
     //! \remark If size of data is more than the capacity of buffer, heap will be
     //! created on time.
     //----------------------------------------------------------------------------
@@ -125,7 +126,7 @@ class CircularBuffer
     //! \brief Return copy of byte at iIndex_ (throw exception if iIndex_ out of
     //! bounds)
     //
-    //! \param [in] iIndex_ integer value
+    //! \param[in] iIndex_ integer value
     //
     //! \return The byte at the provided index.
     //----------------------------------------------------------------------------
@@ -136,34 +137,14 @@ class CircularBuffer
 // Inline Functions
 //-----------------------------------------------------------------------
 
-//----------------------------------------------------------------------------
-//! \brief Returns the current capacity of buffer.
-//----------------------------------------------------------------------------
 inline uint32_t CircularBuffer::GetCapacity() const { return uiMyCapacity; }
 
-//----------------------------------------------------------------------------
-//! \brief Returns number of bytes of data in buffer.
-//----------------------------------------------------------------------------
 inline uint32_t CircularBuffer::GetLength() const { return uiMyLength; }
 
-//----------------------------------------------------------------------------
-//! \brief Delete contents of buffer, internally called Discard method.
-//----------------------------------------------------------------------------
 inline void CircularBuffer::Clear() { Discard(uiMyLength); }
 
-//----------------------------------------------------------------------------
-//! \brief Returns entire circular buffer.
-//----------------------------------------------------------------------------
 inline unsigned char* CircularBuffer::GetBuffer() const { return pucMyBuffer; }
 
-//----------------------------------------------------------------------------
-//! \brief Returns copy of byte at iIndex_ (throw exception if iIndex_ out of
-//! bounds)
-//
-//! \param [in] iIndex_ integer value
-//
-//! \return unsigned character
-//----------------------------------------------------------------------------
 inline unsigned char CircularBuffer::operator[](const int32_t iIndex_) const { return GetByte(iIndex_); }
 
 #endif // CIRCULAR_BUFFER_HPP

src/decoders/common/api/common.hpp

@@ -86,16 +86,16 @@ inline std::ostream& operator<<(std::ostream& os_, const STATUS eStatus_)
 //-----------------------------------------------------------------------
 //! \enum ENCODE_FORMAT
 //! \brief Used to specify the kind of format to re-encode a decoded
-//! message to.  Not every encoder supports these types.
+//! message to. Not every encoder supports these types.
 //-----------------------------------------------------------------------
 enum class ENCODE_FORMAT
 {
-    FLATTENED_BINARY, //!< NovAtel EDIE "Flattened" binary format.  All strings/arrays are padded to
+    FLATTENED_BINARY, //!< NovAtel EDIE "Flattened" binary format. All strings/arrays are padded to
                       //!< maximum length to allow programmatic access.
-    ASCII,            //!< NovAtel ASCII.  If the log was decoded from a SHORT/compressed format, it will be
+    ASCII,            //!< NovAtel ASCII. If the log was decoded from a SHORT/compressed format, it will be
                       //!< encoded to the respective SHORT/compressed format.
     ABBREV_ASCII,     //!< NovAtel Abbreviated ASCII.
-    BINARY,           //!< NovAtel Binary.  If the log was decoded from a SHORT/compressed format, it will be
+    BINARY,           //!< NovAtel Binary. If the log was decoded from a SHORT/compressed format, it will be
                       //!< encoded to the respective SHORT/compressed format.
     JSON,             //!< A JSON object. See HTML documentation for information on fields.
     UNSPECIFIED       //!< No encode format was specified.
@@ -258,6 +258,11 @@ struct MessageDataStruct
 //! Forward declaration for common function headers.
 struct EnumDefinition;
 
+//============================================================================
+//! \class MetaDataBase
+//! \brief Base class for all metadata. Contains data about the data such as header format,
+//! GPS week and milliseconds, and message ID.
+//============================================================================
 class MetaDataBase
 {
   private:

src/decoders/common/api/encoder.hpp

@@ -157,7 +157,7 @@ class EncoderBase
     //----------------------------------------------------------------------------
     //! \brief A constructor for the Encoder class.
     //
-    //! \param[in] pclJsonDb_ A pointer to a JsonReader object.  Defaults to nullptr.
+    //! \param[in] pclJsonDb_ A pointer to a JsonReader object. Defaults to nullptr.
     //----------------------------------------------------------------------------
     EncoderBase(JsonReader* pclJsonDb_ = nullptr);
 

src/decoders/common/api/framer.hpp

@@ -33,8 +33,8 @@
 #include "logger.hpp"
 
 //============================================================================
-//! \class Framer
-//! \brief Base class for all framers.  Contains necessary buffers and member
+//! \class FramerBase
+//! \brief Base class for all framers. Contains necessary buffers and member
 //! variables, defining generic framer operations.
 //============================================================================
 class FramerBase