Meta issue: Error message improvements

[stuartarchibald]

A while back Numba had a very large rewrite of its error handling capabilities, the objectives were:

• To split the error types into roughly two categories 1) those which are likely resolvable by the user/problems with user code etc 2) those which are likely bugs/problems in numba itself.
• Add highlighting to the error messages to make the important bits stand out.
• Include the source line that is problematic in the error message.
• Reduce the size of the traceback in cases where the cause is clear to one frame + a couple of frames to the error rewrite location.
• Add "help" messages with links to on-line documentation.

Some of the above was modelled on what is found in error output modern C/C++ compilers.

The above massively improved the situation but further work is needed, feedback includes:

• Error messages are too technical
• Error messages are too large
• Too much detail
• If there's a typing error it is not clear to what it is referring.
• Tracebacks are still too long.

Following some discussion with @sklam and @esc, some ideas to address the above include:

• Switching around the error message output so that help/docs/guidance comes first, followed by the error message and the source line. This is to try and better match conventional error output where the last few lines of a traceback contain the error.
• Try and put the type information as annotations on the source line in the error message.
• Make type hinting work: Fix PR WIP: Add in better type hinting for functions where this is possible. #3942
• Experiment with lazy frame injection to point to the actual source line of error a the manner of a standard traceback.
• Add better diagnostics tooling (perhaps better type propagation annotations).
• In part using the above, add in a command/link to the new shorter error messages which will add more context to the current error. i.e. Rerun and set environment variable X for expanded diagnostics or Rerun with numba -d <> to see appropriate documentation links etc.
• Make the compiler error messages show at runtime (poison types etc).

Conclusion:

There's a lot of ideas (and more are welcomed) but to start with these probably have the highest ROI:

• Start off with making error messages more terse and doing the reordering, still ask users to report critical errors.
• Add in the type information annotations.
• Make type hinting work: Fix PR WIP: Add in better type hinting for functions where this is possible. #3942

[stuartarchibald]

RE https://gitter.im/numba/numba?at=5d53d776bfd2887f53e733cb, it should be possible to getattr(np, val.__name__) == val or similar when there's an untyped global name of function class to see if it's a NumPy function that's causing the error and if so direct users to specifically look at the supported NumPy functions doc. Ahead of a declarative type system this is the best we can do.

CC @lesshaste