[racket-dev] Error message proposal

Thanks. I'll give this a try as soon as possible.

At Wed, 20 Jun 2012 13:32:32 -0400, Eli Barzilay wrote:
> Here's a concrete proposal for error message structe.  I'll leave the
> highlevel philosophical discussion to the other threads -- but JFYI,
> it does require accepting the problems I mention in the "phrasing"
> thread.
> 
> The general idea is that the first line of an error message is a
> title, and therefore should provide as much helpful information as
> possible, in a short form that usually will fit on a single line.
> This works well with the previous error message format, but broken
> down completely when errors contain a lot of details.  Notable
> examples: list of paths in a cyclic require; the list of "other
> arguments" in type errors; the "probably" explanation on an empty
> () application error; and the suggestion made in the link errors.
> 
> So I'm suggesting that the first line is the "error title" which is
> kept in a form similar to what it was.  That is:
> 
>     [optional short location information]
>     offending token:
>     short description (fits on one line)
> 
> The next line(s) (single or few) add more precise and verbose details
> on the error.  Examples of that are the suggestion I mentioned above,
> or the more accurate description of an unbound identifier error, or
> the `#%app' mention in the () case.
> 
> Following that are the "fields", which can stay in a semi-structured
> textual format for making them parsable.  This structure should be
> specified, but given the above two parts there is no need for being
> very specific with various fields etc.
> 
> As a concrete example, a contract error could be:
> 
>   foo.rkt:10:15: blah: bad input
>     Contract violation in the first argument, your code broke the
>     contract of blah from `some-library/blah'.
>     expected: ...
>     given: ...
>     argument position: ...
>     other arguments: ...
>     full path: ...
>     contract location: ...
>     context: ...
> 
> Note how the first line is imprecise, and provides just a summary.
> The idea is what I discussed previously -- in many cases this error
> will pop up after some revision to the code that you just did, so
> that's enough to know what the problem.
> 
> The following two lines provide more precise information -- and now
> that they're on following lines, that description is no longer
> restriced to be short in any way.  This means, for example, that
> Ryan's semi-complaint about the non-preciseness of unbound identifier
> errors can be addressed.
> 
> Next to that there is the list of fields, and since it's all "down
> after the main texts", it's becoming practical to add a lot of
> relevant information like full paths of the files in question,
> even more detailed explanations on what the error is, suggestions for
> fixing it, pointers to URLs about those errors, etc etc.
> 
> From a presentation point of view (eg, drracket and xrepl), this
> format makes things very easy, since it follows the way you'd want to
> present the information.  For example, drracket can do the following
> pretty easily (just random suggestions, of course):
> 
>   * Show the usual stop-sign line with just the title line (without
>     the location)
>   * When you hover over the line, a popup opens up with the detailed
>     two-line explanation.
>   * When you click the icon, you jump to the relevant location with
>     that popup.
>   * When you hover over the error, or maybe in the popup, you see a
>     list of field names, and clicking them shows the contents of the
>     field.
> 
> Even a textual interface like xrepl can do something similar, where
> the exposition of details goes gradually based on your needs.
> 
> More benefits:
> 
> * It's probably not hard to re-change the code, since it's keeping the
>   multi-line aspect and the fields.
> 
> * Sounds like `error' is not going away in its current format which
>   already does the first-line thing fine.
> 
> * Existing un-updated code works fine too.
> 
> * With the assumption that fields are not initially shown (which
>   translates to some parameter), a lot more information can be added
>   in them, even when they're irrelevant for human consumption.  For
>   example, full paths to source files can blow up the message (eg,
>   paths to the blamed file, the contract definition, and the
>   contracted file; or list of paths in a cycle; or showing a
>   *complete* stacktrace).
> 
> -- 
>           ((lambda (x) (x x)) (lambda (x) (x x)))          Eli Barzilay:
>                     http://barzilay.org/                   Maze is Life!
> 
> _________________________
>   Racket Developers list:
>   http://lists.racket-lang.org/dev