log-level option

CMakeLists.txt

@@ -401,7 +401,7 @@ if (MRDOCS_BUILD_TESTS)
                 "--stdlib-includes=${LIBCXX_DIR}"
                 "--stdlib-includes=${STDLIB_INCLUDE_DIR}"
                 "--libc-includes=${CMAKE_SOURCE_DIR}/share/mrdocs/headers/libc-stubs"
-                --report=2
+                --log-level=warn
         )
         foreach (action IN ITEMS test create update)
             add_custom_target(
@@ -416,7 +416,7 @@ if (MRDOCS_BUILD_TESTS)
                     "--stdlib-includes=${LIBCXX_DIR}"
                     "--stdlib-includes=${STDLIB_INCLUDE_DIR}"
                     "--libc-includes=${CMAKE_SOURCE_DIR}/share/mrdocs/headers/libc-stubs"
-                    --report=2
+                    --log-level=warn
                 DEPENDS mrdocs-test
             )
         endforeach ()

docs/extensions/config-options-reference.js

@@ -90,6 +90,10 @@ function toDefaultValueStr(value) {
 }
 
 function pushOptionBlocks(options, block, parents = []) {
+    function makeOptionID(option) {
+        return [...parents, option.name].join('_') + "_option"
+    }
+
     block.lines.push('<table class="tableblock frame-all grid-all stretch">')
     block.lines.push('<colgroup>')
     block.lines.push('<col style="width: 23.3333%;">')
@@ -108,7 +112,8 @@ function pushOptionBlocks(options, block, parents = []) {
         let optionName = [...parents, option.name].join('.')
         block.lines.push('<tr>')
         block.lines.push(`<td class="tableblock halign-left valign-top">`)
-        block.lines.push(`<code style="color: darkblue">${optionName}</code>`)
+        const colorStr = option['deprecated'] ? 'red' : 'darkblue'
+        block.lines.push(`<a href="#${makeOptionID(option)}"><code style="color: ${colorStr}">${optionName}</code></a>`)
         block.lines.push(`<br/>`)
         block.lines.push(`<span style="color: darkgreen;">(${toTypeStr(option.type)})</span>`)
         let observations = []
@@ -118,8 +123,11 @@ function pushOptionBlocks(options, block, parents = []) {
         if (option['command-line-only']) {
             observations.push('Command line only')
         }
+        if (option['deprecated']) {
+            observations.push(`Deprecated`)
+        }
         if (observations.length !== 0) {
-            block.lines.push(`<br/><br/>`)
+            block.lines.push(`<br/>`)
             let observationsStr = observations.join(', ')
             block.lines.push(`<span style="color: orangered;">(${observationsStr})</span>`)
         }
@@ -134,14 +142,19 @@ function pushOptionBlocks(options, block, parents = []) {
     // Option details
     for (let option of options) {
         let optionName = [...parents, option.name].join('.')
-        block.lines.push(`<div class="paragraph"><p><b><code style="color: darkblue">${optionName}</code></b></p></div>`)
+        const optionID = optionName.replace(/\./g, '_')
+        const colorStr = option['deprecated'] ? 'red' : 'darkblue'
+        block.lines.push(`<div class="paragraph" id="${makeOptionID(option)}"><p><b><code style="color: ${colorStr}">${optionName}</code></b></p></div>`)
         block.lines.push(`<div class="paragraph"><p><i>${option.brief}</i></p></div>`)
         if (option.details) {
             block.lines.push(`<div class="paragraph"><p>${replaceCodeTags(escapeHtml(option.details))}</p></div>`)
         }
         block.lines.push(`<div class="paragraph"><p>`)
         block.lines.push(`<div class="ulist">`)
         block.lines.push(`<ul>`)
+        if (option['deprecated']) {
+            block.lines.push(`<li><span style="color: red;">Deprecated</span>: ${replaceCodeTags(escapeHtml(option['deprecated']))}</li>`)
+        }
         if (option.type) {
             block.lines.push(`<li>Type: ${toTypeStr(option.type)}</li>`)
         } else {

docs/modules/ROOT/pages/config-file.adoc

@@ -149,13 +149,13 @@ namespace my_library
 
 === Private Symbols
 
-The `implementation-detail` and `see-below` options can be used to designate symbols as implementation details or "see below" in the documentation.
+The `implementation-defined` and `see-below` options can be used to designate symbols as implementation details or "see below" in the documentation.
 
 [,yaml]
 ----
 include-symbols:
   - 'my_library::**'
-implementation-detail:
+implementation-defined:
   - 'my_library::detail::**'
 see-below:
   - 'my_library::see_below::**'

docs/modules/ROOT/pages/generators.adoc

@@ -3,12 +3,12 @@
 MrDocs uses a generator to convert the extracted symbols into documentation.
 MrDocs supports multiple output formats that can be specified via the `generate` option:
 
-The `generate` option can be used to specify the output format:
+The `generator` option can be used to specify the output format:
 
 [source,yaml]
 ----
 # ...
-generate: adoc
+generator: adoc
 # ...
 ----
 

docs/modules/ROOT/pages/usage.adoc

@@ -233,7 +233,7 @@ And the user can specify that symbols in the `impl` namespace are implementation
 [source,yaml]
 ----
 # ...
-implementation-detail: impl::**
+implementation-defined: impl::**
 # ...
 ----
 

docs/modules/ROOT/partials/mrdocs-example.yml

@@ -1,3 +1,3 @@
 source-root: ../include
 multipage: false
-generate: adoc
+generator: adoc

docs/modules/ROOT/partials/mrdocs-schema-example.yml

@@ -3,4 +3,4 @@
 
 source-root: ../include
 multipage: false
-generate: adoc
+generator: adoc

docs/mrdocs.schema.json

@@ -190,6 +190,19 @@
       "title": "Standard Library include paths",
       "type": "array"
     },
+    "log-level": {
+      "default": "info",
+      "description": "The reporting level determines the amount of information displayed during the generation of the documentation.",
+      "enum": [
+        "trace",
+        "debug",
+        "info",
+        "warn",
+        "error",
+        "fatal"
+      ],
+      "title": "The minimum reporting level"
+    },
     "multipage": {
       "default": true,
       "description": "Generates a multipage documentation. The output directory must be a directory. This option acts as a hint to the generator to create a multipage documentation. Whether the hint is followed or not depends on the generator.",
@@ -237,11 +250,11 @@
       "type": "boolean"
     },
     "report": {
-      "default": 1,
-      "description": "The reporting level determines the amount of information displayed during the generation of the documentation. The levels are: 0 - no output, 1 - errors only, 2 - errors and warnings, 3 - errors, warnings, and information, 4 - errors, warnings, information, and debug information.",
-      "maximum": 4,
-      "minimum": 0,
-      "title": "The minimum reporting level: 0 to 4",
+      "default": -1,
+      "description": "The reporting level determines the amount of information displayed during the generation of the documentation. The value `-1` delegates the decision to the `log-level` option.",
+      "maximum": 5,
+      "minimum": -1,
+      "title": "The minimum reporting level",
       "type": "integer"
     },
     "see-below": {

include/mrdocs/Support/Error.hpp

@@ -2665,7 +2665,8 @@ namespace report {
 */
 enum class Level
 {
-    debug = 0,
+    trace = 0,
+    debug,
     info,
     warn,
     error,
@@ -2676,6 +2677,7 @@ enum class Level
 */
 struct Results
 {
+    std::size_t traceCount;
     std::size_t debugCount;
     std::size_t infoCount;
     std::size_t warnCount;
@@ -2699,8 +2701,7 @@ results;
 */
 MRDOCS_DECL
 void
-setMinimumLevel(
-    Level level) noexcept;
+setMinimumLevel(Level level) noexcept;
 
 MRDOCS_DECL
 Level
@@ -2825,6 +2826,17 @@ log(
         std::forward<Args>(args)...);
 }
 
+/** Report a message to the console.
+*/
+template<class... Args>
+void
+trace(
+    Located<std::string_view> format,
+    Args&&... args)
+{
+    return log(Level::trace, format, std::forward<Args>(args)...);
+}
+
 /** Report a message to the console.
 */
 template<class... Args>

include/mrdocs/Support/ScopeExit.hpp

@@ -35,6 +35,9 @@ class ScopeExit {
     }
 };
 
+template <class F>
+ScopeExit(F) -> ScopeExit<F>;
+
 template <class T>
 class ScopeExitRestore {
     T prev_;
@@ -66,9 +69,6 @@ class ScopeExitRestore {
     }
 };
 
-template <class F>
-ScopeExit(F) -> ScopeExit<F>;
-
 template <class T>
 ScopeExitRestore(T&) -> ScopeExitRestore<T>;
 

src/lib/AST/ASTVisitor.cpp

@@ -2594,7 +2594,7 @@ checkFileFilters(std::string_view const symbolPath) const
 
 ASTVisitor::ExtractionInfo
 ASTVisitor::
-checkSymbolFilters(Decl const* D, bool AllowParent)
+checkSymbolFilters(Decl const* D, bool const AllowParent)
 {
     // Use the cache
     if (auto const it = extraction_.find(D); it != extraction_.end())

src/lib/AST/ClangHelpers.hpp

@@ -972,7 +972,7 @@ namespace detail {
 #define MRDOCS_SYMBOL_TRACE(D, C) \
     SmallString<256> MRDOCS_SYMBOL_TRACE_UNIQUE_NAME;         \
     detail::printTraceName(D, C, MRDOCS_SYMBOL_TRACE_UNIQUE_NAME); \
-    report::debug("{}", std::string_view(MRDOCS_SYMBOL_TRACE_UNIQUE_NAME.str()))
+    report::trace("{}", std::string_view(MRDOCS_SYMBOL_TRACE_UNIQUE_NAME.str()))
 #endif
 
 } // clang::mrdocs

src/lib/Lib/Config.cpp

@@ -100,7 +100,7 @@ struct PublicSettingsVisitor {
         }
         else if constexpr (std::same_as<DT, int> || std::same_as<DT, unsigned>)
         {
-            return normalizeInteger(name, value, opts);
+            return normalizeInteger(self, name, value, opts);
         }
         else
         {
@@ -328,15 +328,11 @@ struct PublicSettingsVisitor {
     template <std::integral T>
     Expected<void>
     normalizeInteger(
+        PublicSettings& self,
         std::string_view name,
         T& value,
         PublicSettings::OptionProperties const& opts) const
     {
-        if (name == "concurrency" && std::cmp_equal(value, 0))
-        {
-            value = std::thread::hardware_concurrency();
-            return {};
-        }
         MRDOCS_CHECK(
             !opts.minValue || std::cmp_greater_equal(value, *opts.minValue),
             formatError(
@@ -351,6 +347,30 @@ struct PublicSettingsVisitor {
                 name,
                 value,
                 *opts.maxValue));
+
+        if (name == "concurrency" && std::cmp_equal(value, 0))
+        {
+            value = std::thread::hardware_concurrency();
+            return {};
+        }
+
+        if (name == "report" && std::cmp_not_equal(value, static_cast<unsigned>(-1)))
+        {
+            static_assert(
+                static_cast<unsigned>(PublicSettings::LogLevel::Trace) ==
+                static_cast<unsigned>(report::Level::trace));
+            static_assert(
+                static_cast<unsigned>(PublicSettings::LogLevel::Fatal) ==
+                static_cast<unsigned>(report::Level::fatal));
+            MRDOCS_ASSERT(opts.deprecated);
+            report::warn(
+                "`report` option is deprecated, use `log-level` instead");
+            auto const logLevel = static_cast<PublicSettings::LogLevel>(value);
+            auto logLevelStr = PublicSettings::toString(logLevel);
+            report::warn("`report` option: setting `log-level` to \"{}\"", logLevelStr);
+            self.logLevel = logLevel;
+            return {};
+        }
         return {};
     }
 

src/lib/Lib/ConfigOptions.json

@@ -350,9 +350,7 @@
         "details": "The desired level of concurrency: 0 for hardware-suggested.",
         "type": "unsigned",
         "default": 0,
-        "value-mapping": {
-          "0": "std::thread::hardware_concurrency()"
-        }
+        "min-value": 0
       },
       {
         "name": "verbose",
@@ -363,12 +361,28 @@
       },
       {
         "name": "report",
-        "brief": "The minimum reporting level: 0 to 4",
-        "details": "The reporting level determines the amount of information displayed during the generation of the documentation. The levels are: 0 - no output, 1 - errors only, 2 - errors and warnings, 3 - errors, warnings, and information, 4 - errors, warnings, information, and debug information.",
+        "brief": "The minimum reporting level",
+        "details": "The reporting level determines the amount of information displayed during the generation of the documentation. The value `-1` delegates the decision to the `log-level` option.",
         "type": "unsigned",
-        "default": 1,
-        "min-value": 0,
-        "max-value": 4
+        "default": -1,
+        "min-value": -1,
+        "max-value": 5,
+        "deprecated": "Use `log-level` instead"
+      },
+      {
+        "name": "log-level",
+        "brief": "The minimum reporting level",
+        "details": "The reporting level determines the amount of information displayed during the generation of the documentation.",
+        "type": "enum",
+        "values": [
+          "trace",
+          "debug",
+          "info",
+          "warn",
+          "error",
+          "fatal"
+        ],
+        "default": "info"
       },
       {
         "name": "ignore-map-errors",

src/lib/Support/Error.cpp

@@ -186,8 +186,7 @@ print_impl(
 }
 
 void
-setMinimumLevel(
-    Level level) noexcept
+setMinimumLevel(Level const level) noexcept
 {
     level_ = level;
 }
@@ -253,11 +252,10 @@ call_impl(
     {
         llvm::raw_string_ostream os(s);
         f(os);
+        using LT = std::underlying_type_t<Level>;
         if(sourceLocationWarnings_ &&
-           loc && (
-              level == Level::warn ||
-              level == Level::error ||
-              level == Level::fatal))
+           loc &&
+           static_cast<LT>(level) >= static_cast<LT>(Level::error))
         {
             os << "\n\n";
             os << "An issue occurred during execution.\n";
@@ -288,6 +286,9 @@ call_impl(
     }
     switch(level)
     {
+    case Level::trace:
+        ++results.traceCount;
+        break;
     case Level::debug:
         ++results.debugCount;
         break;