Subject: Seeking areas of little or weak documentation
From: Richard Fateman
Date: Wed, 23 Mar 2011 08:44:22 -0700
On 3/23/2011 8:25 AM, Robert Dodier wrote:
> On 3/20/11, Richard Fateman<fateman at eecs.berkeley.edu> wrote:
>
>> I also have periodically suggested that an alphabetized listing of error
>> messages and what they mean would be a service.
> I dunno. I'm not convinced it's worth the trouble.
A first pass could be largely automated. Assuming all error/warning/
messages sent to
the user console goes through one or two standard procedures, use a
program like grep
to find them all. You can then produce a listing
<message> <produced by program X> <in source-file Y>
> "What it means" isn't well-defined in general.
True. But we could probably start to divide them up into categories like
<system error - report this as a bug>
<user error - we think you did something wrong>
<for your information?>
> There are practical problems too. Every time a message
> is created, modified, or removed, the list has to be updated.
I thought you had all this under control for the help (etc) system. :)
> And I suppose all translations of it as well.
ditto:)
> Seems like a tremendous bother with no great benefit.
1. The obvious benefit is for the person who gets an error message and
doesn't understand it,
but would understand a slightly more detailed explanation.
2. The less obvious benefit for the person writing new code who calls
the procedure to
report an error -- the programmer would be encouraged by example (or
constrained!)
by the reporting process to (for example) start the error message with
a fixed string
so that it could be alphabetized.
(What I mean is that an error message "x^2+y was divided by zero"
cannot be found
in an alphabetized list, whereas Division by zero: x^2+y / 0 in <....>.
A constraint might be even better, where the error-message reporting
insisted on a
fixed error name and number, then followed by arbitrary stuff.
3. It might prompt examination of the reporting mechanism to maybe make
better use
of handler-case etc. One could, for example, try to locate errors in
user code instead of
lisp code (meval, simplifier, ...)
> best
>
> Robert Dodier