Re: Required Metrics

[Robert Dewar <robert_dewar@my-deja.com>]

In article <8eutl8$7gh$1@nnrp1.deja.com>,
  Ted Dennison <dennison@telepath.com> wrote:
> In article <8eulom$u8m$1@nnrp1.deja.com>,
>   Robert Dewar <robert_dewar@my-deja.com> wrote:
>
> > It would have been SO much better to make all these
> > documentation "requirements" into implementation advice
> > for several reasons:
> >
> >  3. Implementors have to document which IA they follow and
> >     which they do not, leading to a useful account of how
> >     each IA section is addressed (see the section in the
> >     GNAT RM that does this for example).
>
> But that is a documentation requirement too. If documentation
> requirements became implementation advice, implementors would
no loger
> *have* to document which IA they follow, right? Or is that
> your point?

No, you are missing my point. The IA is stuff that we interpret
informally (in Ken's terms, from a "software engineering" point
of view).

If someone fails to document which IA they follow in a
convenient manner, then they are not formally non-conformant,
but in practice this will not be an issue. It would surprise
me if any vendor does not provide this information, and if
they don't you should definitely complain.

Right now, there is no suggestion AT ALL in the RM, formal or
informal, that vendors should describe how they meet the
documentation "requirements".

Why not? Because they are treated like any other requirements.
I don't have to document that I meet the requirement of
3.2.1:

5   A given type shall not have a subcomponent whose type is the
    given type itself.

or document *how* I meet it, since it is a well defined semantic
requirement (by the way, I suddenly realize that you Ken
converts my general use of semantic into the headings in the
manual, don't make that mistake, semantics includes a lot more
:-)

Similarly the "requirements" associated with pragma Reviewable
do not have any associated documentation requirements on how
they are met, since they are treated by the standard as
equivalent to the 3.2.1(5) statement above, even though they
are not.

That's too bad. When we did the documentation for GNAT, we went
all through annex M making sure we provided all this
information, but we do not include documentation on how we
provide the pragma Reviewable information, because it's not
in Annex M.

Now I definitely agree that this is useful information to
provide, and I made a note to add this to our docs for some
future release, but if the documentation requirements had
been in IA sections, you would have got this automatically.

In practice, making the documentation requirements IA would
INCREASE their utility, not decrease it.







Sent via Deja.com http://www.deja.com/
Before you buy.