Re: Getting GNAT to issue ARM error messages

[dewar@gnat.com]

In article <F6xCoB.Cny@syd.csa.com.au>,
  davidp!nospam!@!nospam!syd.csa.com.au wrote:
> Also, I think that the majority of people developing
> software in Ada *do* have the intellectual capability and
> educational background to read the reference manual,
> which might not be the case in other languages such as C
> C++ (a more diverse
> user base).

I wonder how intimately familiar you are with the Ada 95
RM. It is a VERY difficult document to read in many places,
as I believe is pretty much inevitable if you aim for a
very high level of near-formal precision. Try for example
to understand the accessibility rules from the RM. Very few
people can easily read this material. I speak as someone
who *is* very familiar with the Ada 95 RM.

Note that for me, the situation is totally different
between the Ada 83 and Ada 95 manuals. I often find that
people who want RM references are working from Ada 83
experience, and thinking in terms of the Ada 83 reference
manual.

The kind of people who can successfully read the RM are
generally exactly the kind of people for whom the GNAT
messages should be immediately sufficient. Yes, there are
a few cases of surprising rules and we do use RM references
there.

As I pointed out in my example, gratuitous RM references,
where you take a simple thing like an undefined variable,
and add a completely unhelpful RM reference to some of the
most complex sections of the RM (the ones on visibility),
are simply annoying. Once again in this example:

   "QXR" is undefined

If anyone cannot understand this message, then there is no
way that an RM reference is going to enlightent them.

The useful constructive thing here is to note *specific*
cases of unclear error messages, where additional
explanation or additional warnings are required.

Let me take an example:

  procedure z is
    type r is access integer;
    a : aliased integer;
    b : r := a'access;
  begin
    null;
  end;

This program is obviously incorrect, and indeed I would
expect anyone who is at the level of reading the RM to be
able to immediately figure out the error on line 4, even if
the compiler just said "ERROR" and nothing more.

For the less initiated user, this can be a confusing
situation. We used to simply say:

     4.   b : r := a'access;
                    |
        >>> result must be general access type

But we found many people were confused. For one thing, the
terminology "general access type", completely familiar of
course to anyone who knows the RM, is likely to be
confusing to neophyte users.

Now how to fix things? Add an RM reference? I cannot
imagine that sending someone who does not understand the
above message to the RM could possibly help, and on the
contrary, it would tend to just increase the confusion
level. The RM is NOT the place to learn Ada!

So what did we do in this case, we added an extra message:

     4.   b : r := a'access;
                    |
        >>> result must be general access type
        >>> add "all" to type "r" defined at line 2

and since then, we have got no further confusion queries
on this particular message.

In some other cases, we do find an RM reference helpful,
here is an example:

  1. with System; use System;
  2. procedure z is
  3.   g : Address;
  4.
  5.   type x is record
  6.      m : Integer := 3;
  7.   end record;
  8.
  9.   y : x;
 10.   for y'address use g;
                         |
     >>> invalid address clause for initialized object "y"
     >>> reference to variable "g" not allowed
         (RM 13.1(22))

 11. begin
 12.    null;
 13. end;

The RM reference here is useful to point out a change from
Ada 83 to Ada 95, and a rather obscure rule limiting what
address clauses must be accepted.

I am certainly not saying that all the error messages in
GNAT are perfect, far from it, and we are always putting
in a lot of effort to improve them. But the above should
illustrate the philosophy behind their formulation.

What is useful is not a general recommendation to put in
RM references, most of which would indeed be gratuitous,
but rather comments (preferably sent to report@gnat.com)
about specific messages where you have suggestions for
improvements. If you think an RM reference would be
helpful, then suggest the specific RM reference that you
think would be helpful).

Robert Dewar
Ada Core Technologies

P.S. The point above that people should suggest specific
RM references that they think would be helpful is one I
have made in this and other forum's often before. It is
interesting to note that although we have received hundreds
of suggestions for improving error messages, only *one* of
these suggestions included a specific RM reference (and
indeed it was a helpful suggestion which we followed).



-----------== Posted via Deja News, The Discussion Network ==----------
http://www.dejanews.com/       Search, Read, Discuss, or Start Your Own