Fix: user errors do not invite a bug report - #1306
Open
gennaroprota wants to merge 8 commits into
Open
gennaroprota wants to merge 8 commits into
gennaroprota wants to merge 8 commits into
Conversation
Every error-level message in MrDocs showed the internal source location and contained an invite to file a bug report. A missing config file, for instance, produced that and, with `--warn-as-error`, so did every undocumented symbol. This commit rectifies the situation by emitting such text only for internal errors. Fixes cppalliance#1116.
Contributor
🧾 Changes by Scope
🔝 Top Files
|
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## develop #1306 +/- ##
========================================
Coverage 83.12% 83.12%
========================================
Files 35 35
Lines 3662 3662
Branches 844 844
========================================
Hits 3044 3044
Misses 410 410
Partials 208 208
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
|
An automated preview of the documentation is available at https://1306.mrdocs.prtest2.cppalliance.org/index.html If more commits are pushed to the pull request, the docs will rebuild at the same URL. 2026-09-18 09:09:30 UTC |
The places that quote one error message inside another one used `Error::message()`, which also contains an indication of the source location in which the problem was detected. For instance, a doc-comment warning came out as "HTML <td> tag not followed by </td> (src/mrdocs/AST/ExtractDocComment.cpp:774) at <their file> (6)". Those places quote the reason now, but not the source location. Only detected bugs show source location information now.
`source-root`'s default value is the bare placeholder "<config-dir>", but the resolver only stripped the placeholder when it was followed by a '/'; so the "<...>" text survived verbatim into the path, meaning that every configuration which omitted `source-root` died with a "path does not exist" error. The fix is to treat an empty remainder as ".". A new unit test loads a minimal mrdocs.yml and checks that `source-root` comes back as that file's directory.
The message was likely the result of copy/paste.
This was always the intent, but a few places tested `_NDEBUG` instead of the intended `NDEBUG`, in fact removing the code that reported the exception.
The function was error-prone, in that it used a mapping that was one off the values of the enumerators. Also, nothing in the project used it, and it lived in a private header, so let it go.
gennaroprota
force-pushed
the
fix/user_errors_do_not_invite_a_bug_report
branch
from
September 18, 2026 08:37
68fc5a0 to
3765317
Compare
The format string lacked a placeholder for the error passed with it, so the reason was dropped and the message ended at "because ". The hand-written "Warning: " prefix is also removed, as no other warning carries one. "because" is removed because it may not read well depending on the `err` message.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Every error-level message in MrDocs printed the internal source location and an invitation to file a bug report. For instance, a missing configuration file produced one, and with
--warn-as-errorso did every undocumented symbol, thus a reader was asked to report a MrDocs defect for a mistake in their own input.report::bugis now the only function that does that: it prints the message followed by the version and the source location a bug report needs, whileerror,fatal,warnand the rest print the message alone.Other defects surfaced while going through the reporting code and are fixed in their own commits.
Changes
report::bugnow reports MrDocs defects, with the bug-report details suppressed everywhere else; quoted errors carry their reason without the raising location;source-root's bare-placeholder default resolves to the configuration file's directory; the release-build exception report is compiled in again; the overload-set diagnostic names overload sets rather than enums; the unusedgetLevelis gone.source-rootdefault.Testing
tests/unit/Config.cpp covers the
source-rootdefault: it writes a minimal mrdocs.yml into a temporary directory and asserts the value ofsource-rootcomes back as that file's directory, which the old resolver could not do.The diagnostics themselves are not tested, as that seemed overkill.
Documentation
No page describes the diagnostics or reproduces their wording, so nothing needed updating.
report::bugis public API and carries its doc-comments, which include when to reach for it instead oferror.Closes #1116.