[racket-dev] Error message proposal

From: Eli Barzilay (eli at barzilay.org)
Date: Wed Jun 20 13:32:32 EDT 2012

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"

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.

Posted on the dev mailing list.