fix: user errors do not invite a bug report

include/mrdocs/Support/Report.hpp

@@ -34,7 +34,7 @@
 */
 namespace mrdocs::report {
 
-/** Severity levels attached to reported messags.
+/** Severity levels attached to reported messages.
 */
 enum class Level
 {
@@ -102,17 +102,6 @@ Level
 */
 getMinimumLevel() noexcept;
 
-/** If true, source location information will be
-    printed with warnings, errors, and fatal messages.
-
-    @param b true to enable source location
-    information, false to disable it. The default
-    value is true.
-*/
-MRDOCS_DECL
-void
-setSourceLocationWarnings(bool b) noexcept;
-
 /** Report a message to the console.
 
     @param text The message to print. A
@@ -132,17 +121,12 @@ print(
     @param text The message to print. A
     trailing newline will be added to the
     message automatically.
-
-    @param loc The source location of the report.
-    If this value is null, no location is printed.
 */
 MRDOCS_DECL
 void
 print(
     Level level,
-    std::string const& text,
-    source_location const* loc = nullptr,
-    Error const* e = nullptr);
+    std::string const& text);
 
 /** Parameter type that adds a source location to a value.
 */
@@ -190,7 +174,7 @@ log_impl(
 {
   std::string str =
       std::vformat(fs.value, std::make_format_args(arg0, args...));
-  return print(level, str, &fs.where);
+  return print(level, str);
 }
 
 template<class... Args>
@@ -201,17 +185,9 @@ log_impl(
     Error const& e,
     Args&&... args)
 {
-    // When the message is an error, we send split
-    // the information relevant to the user from
-    // the information relevant for bug tracking
-    // so that users can understand the message.
     std::string str =
         std::vformat(fs.value, std::make_format_args(e.reason(), args...));
-    return print(
-        level,
-        str,
-        &fs.where,
-        &e);
+    return print(level, str);
 }
 
 inline
@@ -221,7 +197,7 @@ log_impl(
     Located<std::string_view> fs)
 {
   std::string str(fs.value);
-  return print(level, str, &fs.where);
+  return print(level, str);
 }
 }
 

src/mrdocs/AST/ASTVisitor.cpp

@@ -2221,10 +2221,7 @@ addMember(
         addMember(I.Members.Macros, *U);
         return;
     }
-    report::error("Cannot push {} of type {} into members of namespace {}",
-        Member.Name,
-        mrdocs::toString(Member.Kind),
-        I.Name);
+    MRDOCS_UNREACHABLE();
 }
 
 void
@@ -2311,9 +2308,7 @@ addMember(RecordTranche& T, Symbol const& Member)
         addMember(T.Usings, *U);
         return;
     }
-    report::error("Cannot push {} of type {} into tranche",
-        Member.Name,
-        mrdocs::toString(Member.Kind));
+    MRDOCS_UNREACHABLE();
 }
 
 void
@@ -2325,10 +2320,7 @@ addMember(EnumSymbol& I, Symbol const& Member) const
         addMember(I.Constants, *U);
         return;
     }
-    report::error("Cannot push {} of type {} into members of enum {}",
-        Member.Name,
-        mrdocs::toString(Member.Kind),
-        I.Name);
+    MRDOCS_UNREACHABLE();
 }
 
 void
@@ -2340,10 +2332,7 @@ addMember(OverloadsSymbol& I, Symbol const& Member) const
         addMember(I.Members, Member);
         return;
     }
-    report::error("Cannot push {} of type {} into members of enum {}",
-        Member.Name,
-        mrdocs::toString(Member.Kind),
-        I.Name);
+    MRDOCS_UNREACHABLE();
 }
 
 void

src/mrdocs/AST/ExtractDocComment.cpp

@@ -200,9 +200,6 @@ convertDirection(clang::comments::ParamCommandPassDirection d)
     case D::InOut:
         return doc::ParamDirection::inout;
     }
-    report::error(
-        "error: unsupported ParamCommandPassDirection <{}>",
-        static_cast<int>(d));
     MRDOCS_UNREACHABLE();
 }
 
@@ -219,7 +216,6 @@ convertCopydoc(unsigned id)
     case T::KCI_copydetails:
         return doc::Parts::description;
     default:
-        report::error("error: unsupported CommandTrait id <{}>", id);
         MRDOCS_UNREACHABLE();
     }
 }
@@ -793,7 +789,7 @@ class DocCommentVisitor
         Expected<doc::TableCell> cellExp = parseTableCell(sub);
         if (!cellExp)
         {
-            warnNear(s, cellExp.error().message());
+            warnNear(s, cellExp.error().reason());
             return;
         }
         row.Cells.push_back(std::move(*cellExp));
@@ -894,7 +890,7 @@ class DocCommentVisitor
         Expected<doc::TableRow> rowExp = parseTableRow(sub);
         if (!rowExp)
         {
-            warnNear(s, rowExp.error().message());
+            warnNear(s, rowExp.error().reason());
             return;
         }
         // Skip rows whose cells all failed to parse: a row with
@@ -1049,7 +1045,7 @@ class DocCommentVisitor
         Expected<doc::TableBlock> tbExp = parseTable(cur);
         if (!tbExp)
         {
-            warnNear(C, tbExp.error().message());
+            warnNear(C, tbExp.error().reason());
             return;
         }
         // A table with no rows (e.g., because every row's content
@@ -1185,7 +1181,7 @@ class DocCommentVisitor
             // written; the rest of the phrase follows as ordinary text.
             if (isSupportedHTMLTag(C->getTagName()))
             {
-                warnOnce(filename, loc.getLine(), compsExp.error().message());
+                warnOnce(filename, loc.getLine(), compsExp.error().reason());
             }
             emplaceInline<doc::TextInline>(
                 C->hasTrailingNewline(),
@@ -1210,7 +1206,7 @@ class DocCommentVisitor
                 // problem in the user's doc comment, not in Mr.Docs: warn
                 // with the location and keep the text instead of failing
                 // the whole run with an internal-error banner.
-                warnOnce(filename, loc.getLine(), r.error().message());
+                warnOnce(filename, loc.getLine(), r.error().reason());
                 emplaceInline<doc::TextInline>(
                     C->hasTrailingNewline(),
                     ensureUTF8(std::move(comps.text)));
@@ -1276,7 +1272,7 @@ class DocCommentVisitor
             auto srcAttr = getAttr("src");
             if (!srcAttr)
             {
-                warnOnce(filename, loc.getLine(), srcAttr.error().message());
+                warnOnce(filename, loc.getLine(), srcAttr.error().reason());
                 return;
             }
             std::string alt = getAttr("alt").value_or(std::string());
@@ -1360,7 +1356,7 @@ class DocCommentVisitor
             warnOnce(
                 files::makePosixStyle(loc.getFilename()),
                 loc.getLine(),
-                r.error().message());
+                r.error().reason());
         }
         else if (comps.tag == "em")
         {
@@ -1761,9 +1757,6 @@ class DocCommentVisitor
         case T::KCI_copybrief:
         case T::KCI_copydetails:
         case T::KCI_copydoc:
-            report::error(
-                "error: inline command {} should be handled elsewhere",
-                cmd->Name);
             MRDOCS_UNREACHABLE();
 
         default:

src/mrdocs/Config.cpp

@@ -591,7 +591,8 @@ load_file(
 {
     auto ft = files::getFileType(configPath);
     MRDOCS_CHECK(ft, formatError(
-        "Config file does not exist: \"{}\"", ft.error(), configPath));
+        "Cannot determine the type of config file \"{}\": {}",
+        configPath, ft.error().reason()));
     if (ft.value() == files::FileType::regular)
     {
         c.config = configPath;
@@ -619,7 +620,8 @@ load_file(
     std::string configYaml;
     auto ft = files::getFileType(configPath);
     MRDOCS_CHECK(ft, formatError(
-        "Config file does not exist: \"{}\"", ft.error(), configPath));
+        "Cannot determine the type of config file \"{}\": {}",
+        configPath, ft.error().reason()));
     if (ft.value() == files::FileType::regular)
     {
         c.config = configPath;
@@ -1119,9 +1121,7 @@ struct ConfigSchemaVisitor {
         MRDOCS_TRY(
             std::string_view const baseDir,
             getBaseDir(referenceDirKey, dirs, settings));
-        if (pos != std::string::npos) {
-            value = value.substr(pos + 1);
-        }
+        value = pos != std::string::npos ? value.substr(pos + 1) : ".";
         return std::string(baseDir);
     }
 };

src/mrdocs/Corpus.cpp

@@ -522,8 +522,7 @@ Corpus::build(
         {
             return Unexpected(err);
         }
-        report::warn(
-            "Warning: mapping failed because ", err);
+        report::warn("Mapping failed: {}", err);
     }
 
     MRDOCS_TRY(auto results, context.results());

src/mrdocs/Engines/JavaScript.cpp

@@ -305,7 +305,7 @@ invokeHelper(Value const& fn, dom::Array const& args)
     auto ret = fn.apply(callArgs);
     if (!ret)
     {
-        return Unexpected(dom::Error(std::string(ret.error().message())));
+        return Unexpected(dom::Error(std::string(ret.error().reason())));
     }
     return ret->getDom();
 }

src/mrdocs/Engines/JavaScript/ValueBridge.ipp

@@ -448,7 +448,7 @@ toDomValue(jerry_value_t v, std::shared_ptr<Context::Impl> const& impl)
             {
                 auto err = makeError(ret);
                 jerry_value_free(ret);
-                return Unexpected(dom::Error(std::string(err.message())));
+                return Unexpected(dom::Error(std::string(err.reason())));
             }
             auto dv = toDomValue(ret, impl);
             jerry_value_free(ret);

src/mrdocs/Engines/Lua/registerHelper.ipp

@@ -155,7 +155,7 @@ invokeHelperRef(
 
     int const rc = lua_pcall(A, static_cast<int>(narg), 1, 0);
     if (rc != LUA_OK)
-        return Unexpected(dom::Error(std::string(luaM_popError(A).message())));
+        return Unexpected(dom::Error(std::string(luaM_popError(A).reason())));
 
     dom::Value result = luaToDom(A, lua_gettop(A));
     lua_pop(A, 1);
@@ -184,7 +184,7 @@ invokeRef(
 
     int const rc = lua_pcall(A, static_cast<int>(narg), 1, 0);
     if (rc != LUA_OK)
-        return Unexpected(dom::Error(std::string(luaM_popError(A).message())));
+        return Unexpected(dom::Error(std::string(luaM_popError(A).reason())));
 
     dom::Value result = luaToDom(A, lua_gettop(A));
     lua_pop(A, 1);

src/mrdocs/Extensions/ExtensionRegistry.cpp

@@ -95,7 +95,7 @@ ExtensionRegistry::applyTransforms(Corpus& corpus, Config const& config) const
             {
                 return Unexpected(formatError(
                     "extension transform '{}': {}",
-                    id, invoked.error().message()));
+                    id, invoked.error().reason()));
             }
         }
     }

src/mrdocs/Extensions/JsBinding.cpp

@@ -189,7 +189,7 @@ loadJsExtensions(std::string const& scriptPath, Config const& config)
     if (!ran.has_value())
     {
         return Unexpected(formatError(
-            "extension '{}': {}", scriptPath, ran.error().message()));
+            "extension '{}': {}", scriptPath, ran.error().reason()));
     }
 
     if (loaded.transforms.empty() && loaded.generators.empty())

src/mrdocs/Generators/hbs/Builder.cpp

@@ -360,7 +360,7 @@ registerUserJsHelpers(
         {
             return Unexpected(formatError(
                 "Error loading utility {}: {}",
-                utilPath, exp.error().message()));
+                utilPath, exp.error().reason()));
         }
     }
 
@@ -417,7 +417,7 @@ registerUserLuaHelpers(
         {
             return Unexpected(formatError(
                 "Error loading utility {}: {}",
-                utilPath, exp.error().message()));
+                utilPath, exp.error().reason()));
         }
     }
 
@@ -680,7 +680,7 @@ operator()(std::ostream& os, T const& I)
             // Reuse the already-built context to avoid recomputing DOM data.
             if (auto exp = callTemplate(os, templateFile, ctx); !exp)
             {
-                return Unexpected(dom::Error(std::string(exp.error().message())));
+                return Unexpected(dom::Error(std::string(exp.error().reason())));
             }
             return {};
         }));
@@ -715,7 +715,7 @@ renderWrapped(
     ctx.set("contents",
             dom::makeInvocable([&](dom::Value const &) -> dom::Expected<dom::Value> {
               if (auto exp = contentsCb(); !exp) {
-                return Unexpected(dom::Error(std::string(exp.error().message())));
+                return Unexpected(dom::Error(std::string(exp.error().reason())));
               }
               return {};
             }));

src/mrdocs/Generators/script/ScriptGenerator.cpp

@@ -129,7 +129,7 @@ buildOutputApi(OutputSink& sink)
                         doAppend);
                     !wrote)
                 {
-                    result = Unexpected(dom::Error(std::string(wrote.error().message())));
+                    result = Unexpected(dom::Error(std::string(wrote.error().reason())));
                 }
                 else
                 {
@@ -212,7 +212,7 @@ build(Corpus const& corpus, Config const& config) const
     if (!invoked)
     {
         result = Unexpected(formatError(
-            "generator '{}': {}", id_, invoked.error().message()));
+            "generator '{}': {}", id_, invoked.error().reason()));
     }
     return result;
 }

src/mrdocs/Support/Error/Error.cpp

@@ -108,7 +108,7 @@ Error(
     for(auto const& err : errors)
     {
         reason_.append("    ");
-        reason_.append(err.message());
+        reason_.append(err.reason());
         reason_.push_back('\n');
     }
     message_ = formatMessage(reason_, where_);