Version 1.5 of si99s/si99-0028-1.txt

Unformatted version of si99s/si99-0028-1.txt version 1.5
Other versions for file si99s/si99-0028-1.txt

!standard 15.23          07-11-17 SI99-0028-1/05
!standard 15.24
!class Binding Interpretation 07-02-16
!status work item 07-10-11
!status ARG Approved 9-0-2 07-06-02
!status work item 07-02-16
!status received 07-02-16
!priority Medium
!difficulty Medium
!qualifier Omission
!subject What does "appropriate kinds" mean?
!summary
Reword the standard so that it is clear what is supposed to be appropriate.
!question
15.23 uses the wording "Appropriate Declaration_Kinds:", while 15.25 uses the wording "Expected Declaration_Kinds:". This wording seems to be different for no reason.
!recommendation
(See summary.)
!wording
Check the entire standard for "Appropriate <something>_Kinds:" and replace by:
"<param_name> expects an element that has one of the following <something>_kinds:"
Afterward, add:
"Raises ASIS_Inappropriate_Element with a Status of Value_Error for any
element that does not have one of these expected kinds."
When there are multiple appropriate kinds for a single parameter, ensure that the wording for additional lists is "or an element with <something_else>_kinds:" (or "and an element..." if that is more appropriate).
Check the entire standard for "Expected <something>_kinds:" and replace by:
"<param_name> expects an element that has one of the following <something>_kinds:"
Ensure that wording that says what happens when an unexpected kinds is passed exists (it does in most cases).
Check the entire standard for "Returns <something>_Kinds:" and replace by:
"Returns an element that has one of the following <something>_Kinds:"
Check the entire standard for "All <something>_Kinds are appropriate." or "All <something>_Kinds are expected." and replace by:
"<param_name> expects any kind of element."
Check the entire standard for "All <something>_Kinds are appropriate except..." or "All <something>_Kinds are expected except...." and replace by:
"<param_name> expects an element that has any <something_Kinds except..."
If the original wording used "appropriate", include the "Raises" paragraph given above.
There are similar changes needed for parameters of type Compilation_Unit, except that "an element" is replaced by "a unit", and ASIS_Inappropriate_Element is replaced by "ASIS_Inappropriate_Compilation_Unit".
for lists of elements, "an element" is replaced by "a list of elements" for instance:
"<param_name> expects a list of elements that each have one of the following <something>_kinds:"
"Returns a list of elements that each have one of the following <something>_Kinds:"
!discussion
The wording is different for a subtle reason: the "appropriate" wording is supposed to mean that an exception is raised if it is violated, whereas the "expected" wording means that an exception is not raised and rather some defined result occurs. This quite tricky.
Moreover, neither wording explains exactly what is appropriate or expected. The operations in question take elements, not kinds; one presumes that this is talking about the kinds of the elements passed to the operation. But one shouldn't have to be presuming anything in a Standard!
The wording for returned elements has a similar problem in that elements, not kinds, are returned.
!appendix

From: Randy Brukardt
Sent: Thursday, February 8, 2007  11:43 PM

Most of the ASIS operations say "Appropriate yadayada_kinds:". But some operations
say "Expected yadayada_kinds:" instead. (See 15.24 and 15.25 for an example.) Questions:

(1) Shouldn't these all be the same? Or is there some subtle different meaning??
(2) Shouldn't there be a clear definition of what these mean? (They mean the "kinds"
    that are allowed as the primary argument to a subprogram. But I haven't seen
    anything saying that; maybe I just missed it.)
(3) Some subprograms have more than one "element" parameter. Shouldn't these clearly
    define which parameter each of these lists refer to?
(4) Similar questions (except the first) apply to the "returns yadayada_kinds:" blocks
    as well.

How should we handle any changes that we determine are necessary?

****************************************************************

From: Pascal Leroy
Sent: Friday, February 9, 2007  1:35 AM

> (1) Shouldn't these all be the same? Or is there some subtle 
> different meaning??

If there is a difference, it is certainly not obvious.  I suspect that
this is just lousy wording, and I suggest using "expected" uniformly.
That's the word that we use in the Ada RM when we want to imply a
requirement on the user (see for instance the containers).  The word
"appropriate" is too vague to be used as a technical term.

> (2) Shouldn't there be a clear definition of what these mean? 

Undoubtedly.

> (3) Some subprograms have more than one "element" parameter. 
> Shouldn't these clearly define which parameter each of these 
> lists refer to?

Yes.

> (4) Similar questions (except the first) apply to the 
> "returns yadayada_kinds:" blocks as well.

I am not sure what is the problem here.  Questions (1) and (3) are
irrelevant, and I don't see that there is anything to define, so it seems
that (2) is irrelevant too.  Maybe the text should be more precise, like:
"returns an element of kinds X, Y or Z".

> How should we handle any changes that we determine are necessary?

I think we need an SI because this has to be validated by the ARG, but the
SI can be fairly generic: there is no point in copying each and every
affected paragraph in the SI.  Something giving the definition(s),
templates to use for the wordings of parameters and return kinds, and the
list of affected sections would be sufficient.

****************************************************************

From: Randy Brukardt
Sent: Saturday, February 10, 2007  11:52 PM

...
> > (4) Similar questions (except the first) apply to the 
> > "returns yadayada_kinds:" blocks as well.
> 
> I am not sure what is the problem here.  Questions (1) and (3) are
> irrelevant, and I don't see that there is anything to define, so it seems
> that (2) is irrelevant too.  Maybe the text should be more precise, like:
> "returns an element of kinds X, Y or Z".

Surely it should be more precise: these functions surely do not return a
yadayada_kind: that's an enumeration of a different type. They return an element
that has that sort of kind.

Perhaps that is the best solution for the others as well:
"<param_name> expects an element with yadayada_kinds:"

(and in the case where there are multiple different kinds for the same parameter):

"or an element with yadayada_kinds:"

Then there is no explanation needed.

> > How should we handle any changes that we determine are necessary?
> 
> I think we need an SI because this has to be validated by the ARG, but the
> SI can be fairly generic: there is no point in copying each and every
> affected paragraph in the SI.  Something giving the definition(s),
> templates to use for the wordings of parameters and return kinds, and the
> list of affected sections would be sufficient.

I think that more precise wording would eliminate the need for definitions, and as we
can see, precise wording is not a lot longer. Why make it (or leave it) confusing? I
agree that templates would be good. I'll write something up, but resist the temptation
to make any changes to the standard until after the ARG has discussed it.

Then all we have to do is convince Bill and Greg to rewrite all of the rest of the
text to be precise. ;-) [I find a lot of it to be just as confusing.]

****************************************************************

From: Randy Brukardt
Sent: Tuesday, February 13, 2007  8:17 PM

>> (1) Shouldn't these all be the same? Or is there some subtle
>> different meaning??

>If there is a difference, it is certainly not obvious.  I suspect that
>this is just lousy wording, and I suggest using "expected" uniformly.
>That's the word that we use in the Ada RM when we want to imply a
>requirement on the user (see for instance the containers).  The word
>"appropriate" is too vague to be used as a technical term.

Well, further research suggests that this lousy wording is intended
(although it still isn't clear what each item applies to).

There is a clear intent that an inappropriate element raises an exception
(2.4.5.1, bullet 4; 5 - ASIS_Inappropriate_Element). OTOH, an "unexpected"
element does not (this typically occurs for functions that return Boolean
values). Unfortunately, I don't see any rule in the primary normative text
that makes this happen (2.4.5.1 is in a section describing the organization
of ASIS).

Still: "Appropriate yadayada_Kinds:" is horribly vague, as it is really
talking about the kind of element passed to a particular parameter. Vague is
not good in a standard, even if the intent can be divined. The wording
should at least say that it imposes a requirement on the user of the
routine; it would be best if it mentioned that inappropriate elements raise
ASIS_Inappropriate_Element. Indeed, I still think Pascal's idea is best:

"<param_name> expects an element with yadayada_kinds:"

(and in the case where there are multiple different kinds for the
same parameter):

"or an element with yadayada_kinds:"

Then adding a boilerplate line:
"An element that does not have one of these kinds raises
ASIS_Inappropriate_Element."
after each grouping.

Note that cases that currently have "expected yadayada_kinds" already say
what happens if the element doesn't have the needed kind.

For "returns", the change is simpler:

"Returns an element with yadayada_kinds:"

since we don't have to raise an exception nor specify the name of the
parameter we're talking about.

Thoughts??

****************************************************************

From: Bill Thomas
Sent: Wednesday, February 14, 2007  3:20 PM

I like your suggestion; it seems to clarify the section. Its probably not a difficult 
change, it just occurs everywhere. For the "raises an exception" bolierplate 
line, how about instead  
  "Raises ASIS_Inappropriate_Element for any element that does not have one 
   of these kinds." 
 
And if it doesn't raise ASIS_Inappropriate_Element, add boilerplate about what 
it does, e.g. 
  "Returns blah for any element that does not have one of these kinds"

****************************************************************


Questions? Ask the ACAA Technical Agent