core: fix docs and formatting

src/core/examples/command-line-example.cc

@@ -57,6 +57,19 @@ SetCbArg(std::string val)
 
 } // unnamed namespace
 
+/**
+ * Print a row containing the name, the default
+ * and the final values of an argument.
+ *
+ * \param [in] label The argument label.
+ * \param [in] defaultValue The default value of the argument.
+ * \param [in] finalValue The final value of the argument.
+ *
+ */
+#define DefaultFinal(label, defaultValue, finalValue)                                              \
+    std::left << std::setw(20) << label + std::string(":") << std::setw(20) << defaultValue        \
+              << finalValue << "\n"
+
 int
 main(int argc, char* argv[])
 {
@@ -123,12 +136,10 @@ main(int argc, char* argv[])
     std::cout << "Argument            Initial Value       Final Value\n"
               << std::left << std::boolalpha;
 
-#define DefaultFinal(label, default, final)                                                        \
-    std::left << std::setw(20) << label + std::string(":") << std::setw(20) << default << final    \
-              << "\n"
-
-    std::cout << DefaultFinal("intArg", intDef, intArg)
-              << DefaultFinal("boolArg", std::boolalpha << boolDef, std::boolalpha << boolArg)
+    std::cout << DefaultFinal("intArg", intDef, intArg) //
+              << DefaultFinal("boolArg",
+                              (boolDef ? "true" : "false"),
+                              (boolArg ? "true" : "false")) //
               << DefaultFinal("strArg", "\"" + strDef + "\"", "\"" + strArg + "\"");
 
     // Look up new default value for attribute

src/core/model/command-line.cc

@@ -493,7 +493,7 @@ CommandLine::PrintDoxygenUsage() const
     }
 
     auto listOptions = [&os](const std::string& head, const Items& items, std::string pre) {
-        os << "\n<dl>\n<h3>" << head << "</h3>\n";
+        os << "\n<h3>" << head << "</h3>\n<dl>\n";
         for (const auto& i : items)
         {
             os << "  <dt>" << pre << i->m_name << " </dt>\n"

src/core/model/command-line.h

@@ -496,7 +496,7 @@ class CommandLine
         /**
          * The argument value.
          * \internal This has to be \c mutable because the Parse()
-         * function is \const in the base class Item.
+         * function is \c const in the base class Item.
          */
         mutable std::string m_value;
     }; // class StringItem
@@ -550,6 +550,8 @@ class CommandLine
 
     /**
      * Strip leading `--` or `-` from options.
+     *
+     * \param [in] param Option name to search
      * \returns \c false if none found, indicating this is a non-option.
      */
     HasOptionName GetOptionName(const std::string& param) const;
@@ -557,6 +559,8 @@ class CommandLine
      * Handle hard-coded options.
      *
      * \note: if any hard-coded options are found this function exits.
+     *
+     * \param [in] args Vector of hard-coded options to handle.
      */
     void HandleHardOptions(const std::vector<std::string>& args) const;
 
@@ -714,7 +718,7 @@ bool UserItemParse<uint8_t>(const std::string& value, uint8_t& dest);
  * \brief Helper to specialize CommandLine::UserItem::GetDefault() on types
  * needing special handling.
  *
- * \param [in] default The default value from the UserItem.
+ * \param [in] defaultValue The default value from the UserItem.
  * \return The string representation of value.
  * @{
  */