Doxygen fixes (#154)

* * Updating conf.py to use absolute path of files relative to itself. This will hopefully fix the readthedocs issues of calling docs/conf.py rather than cd into docs and calling conf.

* * Pushed comment changes for missing variables in doxygen generation
* Changed Threader to use more references and less full pass by value in strings and knowledge bases

* * Removed deprecated doxygen configuration elements
* Added .bak to .gitignore
* Updated docs/conf.py to target build/html, which is supposedly what readthedocs targets now

.gitignore

@@ -1,6 +1,7 @@
 .DS_Store
 .vscode
 
+*.bak
 *.so
 *.o
 *.d

.readthedocs.yaml

@@ -28,7 +28,7 @@ sphinx:
 
 # Optionally build your docs in additional formats such as PDF and ePub
 formats:
-   - pdf
+#   - pdf
 #   - epub
 
 # Optional but recommended, declare the Python requirements required

docs/conf.py

@@ -73,13 +73,13 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path .
 exclude_patterns = [u'_build', 'Thumbs.db', '.DS_Store']
-html_extra_path = ['madara/html']
+html_extra_path = ['build/html']
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'

include/madara/filters/DynamicPrefixPrint.h

@@ -46,6 +46,7 @@ class DynamicPrefixPrint : public AggregateFilter
   /**
    * Prints records and transport context information
    * @param   records           the aggregate records vector
+   * @param   transport_context the transport context where metadata is stored
    * @param   vars              context for querying current program state
    **/
   inline virtual void filter(knowledge::KnowledgeMap& records,

include/madara/filters/PrefixIntConvert.h

@@ -49,7 +49,6 @@ class PrefixIntConvert : public AggregateFilter
   /**
    * Converts the records into integer values
    * @param   records           the aggregate records vector
-   * @param   vars              context for querying current program state
    **/
   inline virtual void filter(knowledge::KnowledgeMap& records,
       const transport::TransportContext&, knowledge::Variables&)

include/madara/filters/PrefixPrint.h

@@ -30,6 +30,7 @@ class PrefixPrint : public AggregateFilter
 public:
   /**
    * Constructor
+   * @param print_verbose   if true, print more verbose information
    * @param source_prefixes the static prefixes to use for printing. If
    *        empty, print all variables. If contains prefixes, only print
    *        variables that begin with contained prefixes

include/madara/knowledge/CheckpointSettings.h

@@ -84,6 +84,7 @@ class CheckpointSettings
    * @param  t_reset_checkpoint  reset the checkpoint modifieds
    * @param  t_ignore_header_check  if true, ignore header checks
    * @param  t_max_buffer_size   the max size in bytes for buffer growth
+   * @param  t_variables_lister  a custom list of variables to print
    **/
   CheckpointSettings(size_t t_buffer_size, bool t_clear_knowledge,
       std::string t_filename = "", uint64_t t_initial_timestamp = 0,

include/madara/knowledge/GetRecord.h

@@ -59,7 +59,7 @@ namespace knowledge
  * @brief Check if a KnowledgeRecord type matches a specified type
  *
  * @param t an instance of the type helper struct to infer the target type
- * @param in the KnowledgeRecord to read from
+ * @param kr the KnowledgeRecord to read from
  * @return true if the types match
  */
 template<typename T>

include/madara/knowledge/containers/NativeCircularBufferConsumer.h

@@ -57,7 +57,6 @@ class NativeCircularBufferConsumer
    * Constructor
    * @param  name       name of the integer in the knowledge base
    * @param  knowledge  the knowledge base that will contain the vector
-   * @param  settings   settings for evaluating the vector
    * @throw exceptions::NameException  bad name ("")
    **/
   NativeCircularBufferConsumer(
@@ -66,8 +65,7 @@ class NativeCircularBufferConsumer
   /**
    * Constructor
    * @param  name      the name of the map within the variable context
-   * @param  knowledge the variable context
-   * @param  settings  settings to apply by default
+   * @param  knowledge the variable contex
    * @throw exceptions::NameException  bad name ("")
    **/
   NativeCircularBufferConsumer(const std::string& name, Variables& knowledge);
@@ -85,24 +83,24 @@ class NativeCircularBufferConsumer
 
   /**
    * Sets the variable name that this refers to
-   * @param name  the name of the variable in the knowledge base
+   * @param name       the name of the variable in the knowledge base
    * @param knowledge  the knowledge base the variable is housed in
    * @throw exceptions::NameException  bad name ("")
    **/
   void set_name(const std::string& name, KnowledgeBase& knowledge);
 
   /**
    * Sets the variable name that this refers to
-   * @param name  the name of the variable in the knowledge base
+   * @param name       the name of the variable in the knowledge base
    * @param knowledge  the knowledge base the variable is housed in
    * @throw exceptions::NameException  bad name ("")
    **/
   void set_name(const std::string& name, Variables& knowledge);
 
   /**
    * Sets the variable name that this refers to
-   * @param name  the name of the variable in the knowledge base
-   * @param knowledge  the ThreadSafeContext the variable is housed in
+   * @param name     the name of the variable in the knowledge base
+   * @param context  the ThreadSafeContext the variable is housed in
    * @throw exceptions::NameException  bad name ("")
    **/
   void set_name(const std::string& name, ThreadSafeContext& context);

include/madara/logger/Logger.h

@@ -14,8 +14,8 @@
  * uses compiler optimizations to ensure that args are not
  * evaluated unless the level is appropriate for the loggers level.
  * This makes logging transparent and minimally invasive, performance wise
- * @param  logger  the logger instance to use
- * @param  level   the logging level
+ * @param  loggering  the logger instance to use
+ * @param  level      the logging level
  **/
 #define madara_logger_log(loggering, level, ...)             \
   if (madara::logger::Logger::get_thread_level() >= 0)       \
@@ -35,8 +35,8 @@
  * This macro uses compiler optimizations to ensure that args are not
  * evaluated unless the level is appropriate for the loggers level.
  * This makes logging transparent and minimally invasive, performance wise
- * @param  logger  the logger pointer to use
- * @param  level   the logging level
+ * @param  loggering  the logger to use
+ * @param  level      the logging level
  **/
 #define madara_logger_ptr_log(loggering, level, ...)                  \
   if (madara::logger::Logger::get_thread_level() >= 0) \
@@ -56,8 +56,8 @@
  * This macro uses compiler optimizations to ensure that args are not
  * evaluated unless the level is appropriate for the loggers level.
  * This makes logging transparent and minimally invasive, performance wise
- * @param  logger  the logger pointer to use
- * @param  level   the logging level
+ * @param  loggering  the logger pointer to use
+ * @param  level      the logging level
  **/
 #define madara_logger_checked_ptr_log(loggering, level, ...)                  \
   if (loggering && madara::logger::Logger::get_thread_level() >= 0) \
@@ -106,7 +106,7 @@
 /**
  * High-performance logger that performs conditional logging based on first arg
  * @param  conditional     the primary logger pointer to use (if not null)
- * @param  logger          the logger that will be used if conditional is true
+ * @param  loggering       the logger that will be used if conditional is true
  * @param  alt_logger_ptr  the secondary logger pointer to use (should be
  *                         not null)
  * @param  level           the logging level

include/madara/threads/Threader.cpp

@@ -10,7 +10,7 @@
 
 madara::threads::Threader::Threader() {}
 
-madara::threads::Threader::Threader(knowledge::KnowledgeBase data_plane)
+madara::threads::Threader::Threader(knowledge::KnowledgeBase& data_plane)
   : data_(std::move(data_plane))
 {
 }
@@ -21,7 +21,7 @@ madara::threads::Threader::~Threader()
   wait();
 }
 
-void madara::threads::Threader::pause(const std::string name)
+void madara::threads::Threader::pause(const std::string& name)
 {
   NamedWorkerThreads::iterator found = threads_.find(name);
 
@@ -40,7 +40,7 @@ void madara::threads::Threader::pause(void)
   }
 }
 
-void madara::threads::Threader::resume(const std::string name)
+void madara::threads::Threader::resume(const std::string& name)
 {
   NamedWorkerThreads::iterator found = threads_.find(name);
 
@@ -60,7 +60,7 @@ void madara::threads::Threader::resume(void)
 }
 
 void madara::threads::Threader::run(
-    const std::string name, BaseThread* thread, bool paused)
+    const std::string& name, BaseThread* thread, bool paused)
 {
   if (name != "" && thread != 0)
   {
@@ -98,7 +98,7 @@ void madara::threads::Threader::run(
 #ifdef _MADARA_JAVA_
 
 void madara::threads::Threader::run(
-    const std::string name, jobject thread, bool paused)
+    const std::string& name, jobject thread, bool paused)
 {
   if (name != "" && thread != 0)
   {
@@ -114,7 +114,7 @@ void madara::threads::Threader::run(
 }
 
 void madara::threads::Threader::run(
-    double hertz, const std::string name, jobject thread, bool paused)
+    double hertz, const std::string& name, jobject thread, bool paused)
 {
   if (name != "" && thread != 0)
   {
@@ -130,7 +130,7 @@ void madara::threads::Threader::run(
 #endif  // _MADARA_JAVA_
 
 void madara::threads::Threader::run(
-    double hertz, const std::string name, BaseThread* thread, bool paused)
+    double hertz, const std::string& name, BaseThread* thread, bool paused)
 {
   if (name != "" && thread != 0)
   {
@@ -166,12 +166,12 @@ void madara::threads::Threader::run(
 }
 
 void madara::threads::Threader::set_data_plane(
-    knowledge::KnowledgeBase data_plane)
+    knowledge::KnowledgeBase& data_plane)
 {
   data_ = std::move(data_plane);
 }
 
-void madara::threads::Threader::terminate(const std::string name)
+void madara::threads::Threader::terminate(const std::string& name)
 {
   NamedWorkerThreads::iterator found = threads_.find(name);
 
@@ -192,7 +192,7 @@ void madara::threads::Threader::terminate(void)
 }
 
 bool madara::threads::Threader::wait(
-    const std::string name, const knowledge::WaitSettings& ws)
+    const std::string& name, const knowledge::WaitSettings& ws)
 {
   bool result(false);
 
@@ -253,7 +253,7 @@ bool madara::threads::Threader::wait(const knowledge::WaitSettings& ws)
 }
 
 bool madara::threads::Threader::wait_for_paused(
-    const std::string name, const knowledge::WaitSettings& ws)
+    const std::string& name, const knowledge::WaitSettings& ws)
 {
   bool result(false);