[racket-dev] Error message proposal

I really like this idea. It seems to be the best of both worlds. I
agree with Robby that more information and structure is good. I also
think, with Eli, that the first line is special for humans and for
existing tools.

Jay

On Wed, Jun 20, 2012 at 11:32 AM, Eli Barzilay <eli at barzilay.org> 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



-- 
Jay McCarthy <jay at cs.byu.edu>
Assistant Professor / Brigham Young University
http://faculty.cs.byu.edu/~jay

"The glory of God is Intelligence" - D&C 93