Fix API documentation for clean rosdoc2 build

Doxyfile

@@ -5,7 +5,7 @@ PROJECT_NUMBER         = master
 PROJECT_BRIEF          = "C++ API providing common utilities and data structures."
 
 # Use these lines to include the generated logging_macro.h (update install path if needed)
-INPUT                  = README.md ./include ./docs
+INPUT                  = README.md QUALITY_DECLARATION.md CONTRIBUTING.md ./include ./docs
 USE_MDFILE_AS_MAINPAGE = README.md
 RECURSIVE              = YES
 OUTPUT_DIRECTORY       = doc_output
@@ -14,6 +14,7 @@ EXTRACT_ALL            = YES
 SORT_MEMBER_DOCS       = NO
 
 GENERATE_LATEX         = NO
+GENERATE_XML           = YES
 EXCLUDE_SYMBOLS        = detail details
 
 ENABLE_PREPROCESSING   = YES

include/rcppmath/clamp.hpp

@@ -52,7 +52,9 @@ constexpr const T & clamp(const T & v, const T & lo, const T & hi)
  * \param[in] comp Comparison object that returns true if the first argument is
  * less than the second.
  * \return Reference to lo if v is less than lo, reference to hi if hi is less than v, otherwise
- * reference to v.
+ * reference to v. "Less than" semantics determined by Comparison object.
+ * \warning Capturing the result of clamp by reference if one of the parameters is rvalue produces
+ * a dangling reference if that parameter is returned.
  * \sa rcppmath::clamp(const T&, const T&, const T&)
  */
 template<class T, class Compare>

include/rcpputils/asserts.hpp

@@ -48,7 +48,7 @@ class RCPPUTILS_PUBLIC AssertionException : public std::exception
   /**
    * \brief Constructor for AssertionException
    *
-   * \param msg The message to display when this exception is thrown.
+   * \param[in] msg The message to display when this exception is thrown.
    */
   explicit AssertionException(const char * msg);
 
@@ -72,7 +72,7 @@ class RCPPUTILS_PUBLIC IllegalStateException : public std::exception
   /**
    * \brief Constructor for IllegalStateException
    *
-   * \param msg The message to display when this exception is thrown.
+   * \param[in] msg The message to display when this exception is thrown.
    */
 
   explicit IllegalStateException(const char * msg);
@@ -88,8 +88,8 @@ class RCPPUTILS_PUBLIC IllegalStateException : public std::exception
 /**
  * \brief Check that an argument condition passes.
  *
- * \param condition condition that is asserted to be true
- * \param msg message to pass to exception when condition is false
+ * \param[in] condition condition that is asserted to be true
+ * \param[in] msg message to pass to exception when condition is false
  * \throw std::invalid_argument if the condition is not met.
  */
 inline void require_true(bool condition, const std::string & msg = "invalid argument passed")
@@ -102,8 +102,8 @@ inline void require_true(bool condition, const std::string & msg = "invalid argu
 /**
  * \brief Check that a state condition passes.
  *
- * \param condition condition to check whether it is true or not
- * \param msg message to pass to exception when condition is false
+ * \param[in] condition condition to check whether it is true or not
+ * \param[in] msg message to pass to exception when condition is false
  * \throw rcpputils::IllegalStateException if the condition is not met.
  */
 inline void check_true(bool condition, const std::string & msg = "check reported invalid state")
@@ -119,8 +119,8 @@ inline void check_true(bool condition, const std::string & msg = "check reported
  * This function behaves similar to assert, except that it throws instead of invoking abort().
  * It is only enabled when NDEBUG is not defined
  *
- * \param condition condition to check whether it's true or not
- * \param msg message to pass to exception when condition is not met.
+ * \param[in] condition condition to check whether it's true or not
+ * \param[in] msg message to pass to exception when condition is not met.
  * \throw rcpputils::AssertionException if the macro NDEBUG is not set and the condition is not met.
  */
 inline void assert_true(bool condition, const std::string & msg = "assertion failed")

include/rcpputils/filesystem_helper.hpp

@@ -83,7 +83,7 @@ class path
   /**
    * \brief Conversion constructor from a std::string path.
    *
-   * \param p A string path split by the platform's string path separator.
+   * \param[in] p A string path split by the platform's string path separator.
    */
   RCPPUTILS_PUBLIC
   path(const std::string & p);  // NOLINT(runtime/explicit): this is a conversion constructor
@@ -183,31 +183,31 @@ class path
   /**
   * \brief Concatenate a path and a string into a single path.
   *
-  * \param other the string compnoent to concatenate
+  * \param[in] other the string compnoent to concatenate
   * \return The combined path of this and other.
   */
   RCPPUTILS_PUBLIC path operator/(const std::string & other) const;
 
   /**
   * \brief Append a string component to this path.
   *
-  * \param other the string component to append
+  * \param[in] other the string component to append
   * \return *this
   */
   RCPPUTILS_PUBLIC path & operator/=(const std::string & other);
 
   /**
   * \brief Concatenate two paths together.
   *
-  * \param other the path to append
+  * \param[in] other the path to append
   * \return The combined path.
   */
   RCPPUTILS_PUBLIC path operator/(const path & other) const;
 
   /**
   * \brief Append a string component to this path.
   *
-  * \param other the string component to append
+  * \param[in] other the string component to append
   * \return *this
   */
   RCPPUTILS_PUBLIC path & operator/=(const path & other);
@@ -220,23 +220,23 @@ class path
 /**
  * \brief Check if the path is a regular file.
  *
- * \param p The path to check
+ * \param[in] p The path to check
  * \return True if the path exists, false otherwise.
  */
 RCPPUTILS_PUBLIC bool is_regular_file(const path & p) noexcept;
 
 /**
  * \brief Check if the path is a directory.
  *
- * \param p The path to check
+ * \param[in] p The path to check
  * \return True if the path is an existing directory, false otherwise.
  */
 RCPPUTILS_PUBLIC bool is_directory(const path & p) noexcept;
 
 /**
  * \brief Get the file size of the path.
  *
- * \param p The path to get the file size of.
+ * \param[in] p The path to get the file size of.
  * \return The file size in bytes.
  *
  * \throws std::sytem_error
@@ -246,7 +246,7 @@ RCPPUTILS_PUBLIC uint64_t file_size(const path & p);
 /**
  * \brief Check if a path exists.
  *
- * \param path_to_check The path to check.
+ * \param[in] path_to_check The path to check.
  * \return True if the path exists, false otherwise.
  */
 RCPPUTILS_PUBLIC bool exists(const path & path_to_check);
@@ -270,8 +270,8 @@ RCPPUTILS_PUBLIC path temp_directory_path();
  * The underlying implementation keeps generating paths until one that does not exist is found.
  * This guarantees that there will be no existing files in the returned directory.
  *
- * \param base_name User-specified portion of the created directory
- * \param parent The parent path of the directory that will be created
+ * \param[in] base_name User-specified portion of the created directory
+ * \param[in] parent_path The parent path of the directory that will be created
  * \return A path to a newly-created directory with base_name and a 6-character unique suffix
  *
  * \throws std::system_error If any OS APIs do not succeed.
@@ -293,14 +293,15 @@ RCPPUTILS_PUBLIC path current_path();
  * \brief Create a directory with the given path p.
  *
  * This builds directories recursively and will skip directories if they are already created.
+ * \param[in] path The path at which to create the directory.
  * \return Return true if the directory already exists or is created, false otherwise.
  */
 RCPPUTILS_PUBLIC bool create_directories(const path & p);
 
 /**
  * \brief Remove the file or directory at the path p.
  *
- * \param p The path of the object to remove.
+ * \param[in] p The path of the object to remove.
  * \return true if the file exists and it was successfully removed, false otherwise.
  */
 RCPPUTILS_PUBLIC bool remove(const path & p);
@@ -310,7 +311,7 @@ RCPPUTILS_PUBLIC bool remove(const path & p);
  *
  * Additionally to \sa remove, remove_all removes a directory and its containing files.
  *
- * \param The path of the directory to remove.
+ * \param[in] p The path of the directory to remove.
  * \return true if the directory exists and it was successfully removed, false otherwise.
  */
 RCPPUTILS_PUBLIC bool remove_all(const path & p);
@@ -320,8 +321,8 @@ RCPPUTILS_PUBLIC bool remove_all(const path & p);
  *
  * An extension is defined as text starting from the end of a path to the first period (.) character.
  *
- * \param file_path The file path string.
- * \param n_times The number of extensions to remove if there are multiple extensions.
+ * \param[in] file_path The file path string.
+ * \param[in] n_times The number of extensions to remove if there are multiple extensions.
  * \return The path object.
  */
 RCPPUTILS_PUBLIC path remove_extension(const path & file_path, int n_times = 1);
@@ -337,8 +338,8 @@ RCPPUTILS_PUBLIC bool operator!=(const path & a, const path & b);
 /**
 * \brief Convert the path to a string for ostream usage, such as in logging or string formatting.
 *
-* \param os The stream to send the path string to
-* \param p The path to stringify
+* \param[in] os The stream to send the path string to
+* \param[in] p The path to stringify
 * \return The ostream, for chaining
 */
 RCPPUTILS_PUBLIC std::ostream & operator<<(std::ostream & os, const path & p);

include/rcpputils/shared_library.hpp

@@ -63,7 +63,8 @@ class SharedLibrary
   has_symbol(const char * symbol_name);
 
   /**
-   * @copydoc SharedLibrary::has_symbol(const char *)
+   * \param[in] symbol_name name of the symbol inside the shared library
+   * \return if symbols exists returns true, otherwise returns false.
    */
   RCPPUTILS_PUBLIC
   bool
@@ -80,8 +81,12 @@ class SharedLibrary
   void *
   get_symbol(const char * symbol_name);
 
+  /// Return shared library symbol pointer.
   /**
-   * @copydoc SharedLibrary::get_symbol(const char *)
+   * \param[in] symbol_name name of the symbol inside the shared library
+   * \return shared library symbol pointer, if the symbol doesn't exist then throws a
+   * runtime_error exception
+   * \throws std::runtime_error if the symbol doesn't exist in the shared library
    */
   RCPPUTILS_PUBLIC
   void *

include/rcpputils/split.hpp

@@ -44,6 +44,7 @@
 namespace rcpputils
 {
 
+/// @cond
 /// Split a specified input into tokens using a delimiter and a type erased insert iterator.
 /**
  * The returned vector will contain the tokens split from the input
@@ -73,6 +74,7 @@ split(const std::string & input, char delim, InsertIterator & it, bool skip_empt
     it = item;
   }
 }
+/// @endcond
 
 /// Split a specified input into tokens using a delimiter.
 /**

include/rcpputils/thread_safety_annotations.hpp

@@ -32,12 +32,21 @@
 * [their documentation](https://clang.llvm.org/docs/ThreadSafetyAnalysis.html) for more info
 */
 
+/// @cond
 // Prefixing all macros to avoid potential conflict with other projects.
+/**
+  * \def RCPPUTILS_THREAD_ANNOTATION_ATTRIBUTE__(x)
+  * \brief Enable thread safety attributes only with clang.
+  *
+  * The attributes can be safely erased when compiling with other compilers.
+  * https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h
+  */
 #if defined(__clang__) && defined(_LIBCPP_HAS_THREAD_SAFETY_ANNOTATIONS) && (!defined(SWIG))
 #define RCPPUTILS_THREAD_ANNOTATION_ATTRIBUTE__(x)   __attribute__((x))
 #else
 #define RCPPUTILS_THREAD_ANNOTATION_ATTRIBUTE__(x)   // no-op
 #endif
+/// @endcond
 
 /**
   * \brief Defined for negation functionality