feat: source location included in warnings for unresolved references #704
Conversation
|
An automated preview of the documentation is available at https://704.mrdocs.prtest2.cppalliance.org/index.html |
| // This warning shouldn't be triggered if the symbol has | ||
| // been explicitly marked excluded in mrdocs.yml | ||
| if(! resolveReference(N)) | ||
| { | ||
| report::warn("Failed to resolve reference to '{}' from '{}'", | ||
| N.string, current_->Name); | ||
| report::warn("Failed to resolve reference to '{}' from '{}' at file '{}' line {} column {}", |
There was a problem hiding this comment.
#528 describes one problem B: the need for source file information in warnings and errors. This is important.
However, the original problem A, which motivated the #if 0, is independent: this message is a false positive in the caller's context.
For instance, if I have these functions:
detail::my_impl func_a();
std::optional<int> func_b();Because detail::my_impl is an implementation-defined type and std::optional is not part of my project, I would get messages like "Failed to resolve reference to 'detail::my_impl' from 'func_a()' at file 'X' line Y column Z" or "Failed to resolve reference to 'std::optional<int>' from 'func_b()' at file 'X' line Y column Z".
Having the line numbers improves the message (problem B). But that doesn't change the fact that the message is wrong (problem A) because these return types are not supposed to be documented, and the user is not obliged not to use undocumented types. So, the user is correct but still receiving a warning.
So, if we solve problem B without solving problem A, it doesn't justify removing #if 0 from the caller here. The possible solutions would be:
- Fixing these false negatives so the caller only prints messages when they are correct. The message would not be a false negative if, instead of the return type in code, the reference were an explicit
@refin the javadoc that can't be resolved. - Leaving the
#if 0there, leaving the potential improved error messages there, and create another issue for these false negatives.
Also, regarding #528, he got this warning without the source location. However, the issue is about warnings and errors in general, and that's not the only warning MrDocs emits.
|
An automated preview of the documentation is available at https://704.mrdocs.prtest2.cppalliance.org/index.html |
fixes #528