refactor: split error message from source location in reports

fix #672

include/mrdocs/Support/Error.hpp

@@ -2775,7 +2775,62 @@ void
 print(
     Level level,
     std::string const& text,
-    source_location const* loc = nullptr);
+    source_location const* loc = nullptr,
+    Error const* e = nullptr);
+
+namespace detail {
+template<class Arg0, class... Args>
+requires (!std::same_as<std::decay_t<Arg0>, Error>)
+void
+log_impl(
+    Level level,
+    Located<std::string_view> fs,
+    Arg0&& arg0,
+    Args&&... args)
+{
+    std::string str = fmt::vformat(
+        fs.value,
+        fmt::make_format_args(arg0, args...));
+    return print(
+        level,
+        str,
+        &fs.where);
+}
+
+template<class... Args>
+void
+log_impl(
+    Level level,
+    Located<std::string_view> fs,
+    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 = fmt::vformat(
+        fs.value,
+        fmt::make_format_args(e.reason(), args...));
+    return print(
+        level,
+        str,
+        &fs.where,
+        &e);
+}
+
+inline
+void
+log_impl(
+    Level level,
+    Located<std::string_view> fs)
+{
+    return print(
+        level,
+        {},
+        &fs.where);
+}
+}
 
 /** Format a message to the console.
 
@@ -2791,17 +2846,15 @@ print(
 */
 template<class... Args>
 void
-format(
+log(
     Level level,
     Located<std::string_view> fs,
     Args&&... args)
 {
-    return print(
+    return detail::log_impl(
         level,
-        fmt::vformat(
-            fs.value,
-            fmt::make_format_args(args...)),
-        &fs.where);
+        fs,
+        std::forward<Args>(args)...);
 }
 
 /** Report a message to the console.
@@ -2812,12 +2865,7 @@ debug(
     Located<std::string_view> format,
     Args&&... args)
 {
-    return print(
-        Level::debug,
-        fmt::vformat(
-            format.value,
-            fmt::make_format_args(args...)),
-        &format.where);
+    return log(Level::debug, format, std::forward<Args>(args)...);
 }
 
 /** Report a message to the console.
@@ -2828,12 +2876,7 @@ info(
     Located<std::string_view> format,
     Args&&... args)
 {
-    return print(
-        Level::info,
-        fmt::vformat(
-            format.value,
-            fmt::make_format_args(args...)),
-        &format.where);
+    return log(Level::info, format, std::forward<Args>(args)...);
 }
 
 /** Report a message to the console.
@@ -2844,12 +2887,7 @@ warn(
     Located<std::string_view> format,
     Args&&... args)
 {
-    return print(
-        Level::warn,
-        fmt::vformat(
-            format.value,
-            fmt::make_format_args(args...)),
-        &format.where);
+    return log(Level::warn, format, std::forward<Args>(args)...);
 }
 
 /** Report a message to the console.
@@ -2860,12 +2898,7 @@ error(
     Located<std::string_view> format,
     Args&&... args)
 {
-    return print(
-        Level::error,
-        fmt::vformat(
-            format.value,
-            fmt::make_format_args(args...)),
-        &format.where);
+    return log(Level::error, format, std::forward<Args>(args)...);
 }
 
 /** Report a message to the console.
@@ -2876,12 +2909,7 @@ fatal(
     Located<std::string_view> format,
     Args&&... args)
 {
-    return print(
-        Level::fatal,
-        fmt::vformat(
-            format.value,
-            fmt::make_format_args(args...)),
-        &format.where);
+    return log(Level::fatal, format, std::forward<Args>(args)...);
 }
 
 } // report

src/lib/Lib/CorpusImpl.cpp

@@ -187,9 +187,8 @@ build(
             taskGroup.async(
             [&, idx = ++index, path = std::move(file)]()
             {
-                report::format(reportLevel,
+                report::log(reportLevel,
                     "[{}/{}] \"{}\"", idx, files.size(), path);
-
                 processFile(path);
             });
         }
@@ -217,7 +216,7 @@ build(
         return Unexpected(results.error());
     corpus->info_ = std::move(results.value());
 
-    report::format(reportLevel,
+    report::log(reportLevel,
         "Extracted {} declarations in {}",
         corpus->info_.size(),
         format_duration(clock_type::now() - start_time));

src/lib/Support/Error.cpp

@@ -10,6 +10,7 @@
 
 #include "lib/Support/Error.hpp"
 #include <mrdocs/Support/Path.hpp>
+#include <mrdocs/Version.hpp>
 #include <llvm/Support/Mutex.h>
 #include <llvm/Support/raw_ostream.h>
 #include <llvm/Support/Signals.h>
@@ -201,13 +202,14 @@ void
 print(
     Level level,
     std::string const& text,
-    source_location const* loc)
+    source_location const* loc,
+    Error const* e)
 {
     call_impl(level,
         [&](llvm::raw_ostream& os)
         {
             os << text;
-        }, loc);
+        }, loc, e);
 }
 
 //------------------------------------------------
@@ -230,7 +232,8 @@ void
 call_impl(
     Level level,
     std::function<void(llvm::raw_ostream&)> f,
-    source_location const* loc)
+    source_location const* loc,
+    Error const* e)
 {
     std::string s;
     if(level >= level_)
@@ -242,11 +245,22 @@ call_impl(
             level == Level::error ||
             level == Level::fatal))
         {
-            os << "\n" <<
-                fmt::format(
-                    "    Reported at {}({})",
-                    ::SourceFileNames::getFileName(loc->file_name()),
-                    loc->line());
+            os << "\n\n";
+            os << "An issue occurred during execution.\n";
+            os << "If you believe this is a bug, please report it at https://github.com/cppalliance/mrdocs/issues\n"
+                  "with the following details:\n";
+            os << fmt::format("    MrDocs Version: {} (Build: {})\n", project_version, project_version_build);
+            if (e)
+            {
+                os << fmt::format(
+                    "    Error Location: `{}` at line {}\n",
+                    ::SourceFileNames::getFileName(e->location().file_name()),
+                    e->location().line());
+            }
+            os << fmt::format(
+                "    Reported From: `{}` at line {}",
+                ::SourceFileNames::getFileName(loc->file_name()),
+                loc->line());
             // VFALCO attach a stack trace for Level::fatal
         }
         os << '\n';

src/lib/Support/Error.hpp

@@ -119,7 +119,8 @@ void
 call_impl(
     Level level,
     std::function<void(llvm::raw_ostream&)> f,
-    source_location const* loc);
+    source_location const* loc,
+    Error const* e = nullptr);
 
 /** Formatted reporting to a live stream.
 

src/tool/ToolMain.cpp

@@ -135,7 +135,7 @@ mrdocs_main(int argc, char const** argv)
     auto exp = DoGenerateAction(configPath, dirs, argv);
     if (!exp)
     {
-        report::error("Generating reference failed: {}", exp.error().message());
+        report::error("Generating reference failed: {}", exp.error());
     }
     if (report::results.errorCount > 0 ||
         report::results.fatalCount > 0)