Re: GNAT documentation question

[Robert A Duff <bobduff@shell01.TheWorld.com>]

Simon Wright <simon@pushface.org> writes:

> dewar@gnat.com (Robert Dewar) writes:
> 
> > That's straightforward. If you want Annex D dispatching rules
> > (that's the semantically significant issue here), then you need to
> > use the pragmas documented in Annex D to have this effect. I would
> > be surprised if there was anything else to this issue. In other
> > words, real time priorities are not an end here, they are simply a
> > means to an end, the end being the proper implementation of annex D
> > features.
> 
> Our point of view was:
> 
> * we have a mixed language, multi-process program
> 
> * we need parts of it to run with priorities higher than those of
>   normal processes
> 
> * we can use priocntl to get this to happen (this was Solaris)
> 
> * wow! if we run as root, GNAT does what we want! (this was 3.11, I
>   think)
> 
> so the question of whether we had Annex D dispatching rules never
> entered our heads.

This is a good example of why I think Annex M is useless.  This
programmer wants to know how to fiddle with *process* priorities, which
have nothing to do with what's in the RM, and in fact Annex M doesn't
give any pressure toward answering it.  How could it?  The RM knows
nothing of processes.  Nonetheless, good documentation would explain how
Ada priorities affect process priorities and the like.

You can't legislate "good documentation", any more than "morality".

I think compiler documentation should be driven by "what do we think the
programmer wants to know about" rather than by "the RM says we have to
document certain things".

> We were delighted to have found a solution, so never raised the
> question with ACT. Had we still been supported on that contract when
> we discovered the changed behaviour, we would of course have asked!

When I wrote the docs for AdaMagic for the SHARC chip, I *first* wrote
what I thought was useful: sections about "how to debug" and "how to
handle interrupts", etc, with examples and whatnot.  This was somewhat
driven by my own knowledge, and somewhat by questions from customers.
Then I went through Annex M, and if it said I must document
something-or-other about interrupts, I referred the reader to the
interrupt section, rather than inserting some out-of-context factoid
about interrupts in Annex M.

Our documentation of Annex M ensures that we obey the rules (although as
Robert Dewar pointed out, this can't be formally verified), but it not
particularly useful to users.

- Bob