In-progress links in exception messages (plus misc exception msg improvements)

[alistairjevans]

Trying out links in the exception messages to see if people are happy with the approach.

See https://autofac.readthedocs.io/en/exception-docs/faq/exception-info.html for a (hidden) branch of documentation that contains the linked content (branch is at https://github.com/autofac/Documentation/tree/exception-docs).

Redirects are set up using readthedocs built-in redirect behaviour, to give us a shorter link for the full one that includes an anchor tag:

So, visiting https://autofac.rtfd.io/help/no-constructors-bindable (in the exception message) will go through the redirect and end up at the right place.

I've also simplified the "NoConstructorsBindable" message to show a simpler message if they are using the DefaultConstructorFinder (99.99% of cases I'd imagine), just to reduce potential confusion.

[tillig]

Looking good! I think this will help a lot to reduce the "I didn't read the exception message" questions on SO. Maybe. 🤔

If the exception doc is going to show up in the table of contents on the doc site it might need either:

• a title like "What does this DependencyResolutionException mean?" or
• sections in the doc for each exception type if we plan on handling all the explanations on one page

That way if we handle more exception types we can organize by type.

[alistairjevans]

Might have to end up with a doc per-error; redirects don't seem to like anchor tags very much. If so, probably a section per exception type, then divided again by error.

[codecov]

Codecov Report

Base: 77.98% // Head: 77.97% // Decreases project coverage by -0.01% ⚠️

Coverage data is based on head (4fe918e) compared to base (0362f7e).
Patch coverage: 100.00% of modified lines in pull request are covered.

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #1281      +/-   ##
===========================================
- Coverage    77.98%   77.97%   -0.02%     
===========================================
  Files          195      195              
  Lines         5587     5593       +6     
  Branches      1119     1120       +1     
===========================================
+ Hits          4357     4361       +4     
- Misses         716      717       +1     
- Partials       514      515       +1     

Impacted Files	Coverage Δ
.../Core/Activators/Reflection/ReflectionActivator.cs	89.93% <100.00%> (+0.42%)	⬆️
src/Autofac/Util/SequenceGenerator.cs	71.42% <0.00%> (-28.58%)	⬇️

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report at Codecov.
📢 Do you have feedback about the report comment? Let us know in this issue.

[tillig]

This appears to have gotten pretty stale. I think it's still interesting to finish, though. Is there something I can do to help get it out the door? If we need one-doc-per-error I may be able to start that, possibly under the "Troubleshooting" section. I can use the changes here as a guide for which exceptions need a doc unless you have a list.

[alistairjevans]

Yeah, apologies for letting this stagnate so long, lost impetus on it for some reason. Basically, the mechanic is all there, so all that needs doing is the documentation pages, and then updating the messages with the links.

That exception-docs should still be good on the docs repo, but will probably need merging from latest.

[tillig]

I think what I'll do first is try to update the doc site so we have a more robust troubleshooting section that will eventually house specific exception docs underneath. Since the redirects don't like #anchors it's easy enough to do page-per-exception, which is generally fine to avoid overwhelming folks with documentation and risk having them skim and still not get it. I'll probably add the documentation for the exception you have here as the first one.

After that we can figure out what to do about the code. It looks like it's in your fork rather than a branch right in this repo, which is fine, but means I can't easily pick it up and run with it. Not a huge deal, doesn't look like too much has changed here so applying the diff to a new branch I can access should be easy enough.

Once I get some momentum here, we can close this PR.

[tillig]

I think I have the exception-docs branch of the docs repo updated with a decent structure to start adding things. Give that a look if you get a chance. Since I moved things, once that gets published I'll probably have to put a redirect in place to send the old debugging-and-troubleshooting.html to the new section, but that should be OK.

[alistairjevans]

Is it easier if I retarget this PR to a feature branch in the Autofac repo rather than develop, and you can then base on that?

I'll merge latest develop in here anyway.

[alistairjevans]

OK, this is up-to-date with develop now. You want to update the PR to point at a new local repo branch off develop?

[tillig]

Actually, yeah, then I can just pick up where you left off. That'd be awesome.

[alistairjevans]

OK, these changes are now in feature/exception-msg-links.