Version 1.4 of ai12s/ai12-0447-1.txt

!standard 3.9(29) 22-12-16 AI12-0447-1/02

Reword some notes.

The JTC1 Directives, Part 2, do not allow text that reads like a requirement or recommendation in Notes or Examples.

[Editor's note: The ISO editors flagged the phrases quoted at the start of the text in square brackets.]

Modify 3.9(29):

NOTE 3   Class-wide types are defined to have unknown discriminants (see 3.7). This means that{, by the rules in 3.7 for objects with unknown discriminants,} objects of a class-wide type {are illegal unless they are}[have to be] explicitly initialized (whether created by an object_declaration or an allocator), and that aggregates {are illegal unless they are}[have to be] explicitly qualified with a specific type when their expected type is class-wide.

[“have to be”, twice. The fact that the language requires these (elsewhere) seems important, it’s not a statement of fact. We've already clearly marked that we are talking about a consequence and they still are not happy. Tucker suggests talking about "legal" and "illegal" instead, thus the rewording above.]

Modify 3.9.1(8):

NOTE 3   {By the rules given in 3.8, a}[A] name that denotes a component (including a discriminant) of the parent type is {illegal}[not allowed] within the record_extension_part. Similarly, a name that denotes a component defined within the record_extension_part is {illegal}[not allowed] within the record_extension_part. [It is permissible to use a]{A} name that denotes a discriminant of the record extension{ is legal}, providing {that it refers to a discriminant defined in}[there is] a new known_discriminant_part in the enclosing type declaration.[ (The full rule is given in 3.8.) ]

[“It is permissible”. This isn’t talking about a permission anyway.]

Modify 3.9.1(9):

NOTE 4   {By the rules given in 8.3, each}[Each] visible component of a record extension {will}[has to] have a unique name, whether the component is (visibly) inherited from the parent type or declared in the record_extension_part[ (see 8.3)].

[“has to be”. The fact that the language requires this (elsewhere) seems important, it’s not a statement of fact.]

Modify 3.9.3(12):

NOTE 1   Abstractness is not inherited; {a type is abstract only if}[to declare an abstract type,] the reserved word abstract {is}[has to be] used in the declaration of the type extension.

[“has to be”. The fact that this is necessary is the point, we need a substantial rewording.]

Modify 3.10.1(13):

NOTE 1   Within a declarative_part, an incomplete_type_declaration and a corresponding full_type_declaration cannot be separated by an intervening body. This is because{, by the rules given in 13.14,} a type {is illegal if it is not}[has to be] completely defined before it is frozen, and a body freezes all types declared prior to it in the same declarative_part[ (see 13.14)].

[“has to be”. The fact that the language requires this (elsewhere) seems important, it’s not a statement of fact.]

Modify 4.1.2(8):

NOTE 1   {By the rules given in 3.10.2, a}[A] slice is {illegal}[not permitted] as the prefix of an Access attribute_reference, even if the components or the array as a whole are aliased.[ See 3.10.2.]

[“is not permitted”. We could have talked about impossibility, as in “cannot be used as the prefix”.]

Modify 4.1.4(17/2):

NOTE 2   {By the}[In] general{ rules given above}, {there is no expected type or profile for }the name in a prefix of an attribute_reference (or a range_attribute_reference){, which means that no context can be used to resolve the name}[ has to be resolved without using any context]. However, {by the rules given in 3.10.2 for}[in] the case of the Access attribute, the expected type for the attribute_reference {will}[has to] be a single access type, and the resolution of the name can {make use of the designated type or profile of this}[use the fact that the type of the object or the profile of the callable entity denoted by the prefix has to match the designated type or be type conformant with the designated profile of the] access type.

[“has to be”, three times. Again, the fact that the language requires this seems important.]

Modify 4.3.1(21):

NOTE   {By the rules given above, for}[For] a record_aggregate with positional associations, expressions specifying discriminant values appear first {and in the same order as their corresponding discriminant_specifications, }since the known_discriminant_part {occurs}[is given] first in the declaration of the type[; they have to be in the same order as in the known_discriminant_part].

[“have to be”. This is clearly talking about a language requirement (given elsewhere).]

Modify 4.3.2(9):

NOTE 1   {By the rules given in 4.3.1, if}[If] all components of the value of the extension_aggregate are determined by the ancestor_part, then the record_component_association_list {will}[is required to] be simply null record.

[“is required to be”; this is talking about a requirement imposed (on programmers) by rules in 7.3.1. Saying it is a “statement of fact” makes no sense; the programmer surely could write other things, they just wouldn’t be legal. Is "can only be null record" better than "will be simply null record"? **]

Modify 9.7.1(22):

NOTE   A selective_accept {can}[is allowed to] have several open delay_alternatives. A selective_accept {can}[is allowed to] have several open accept_alternatives for the same entry.

[“is allowed to” (twice). “can” works here.]

Modify 10.2.1(27):

NOTE 1   A preelaborated library unit {can}[is allowed to] have nonpreelaborable children.

[“is allowed to”. “can” works here.]

Modify 10.2.1(28):

NOTE 2   A library unit that is declared pure {can}[is allowed to] have impure children.

[“is allowed to”. “can” works here.]

Modify 11.4.2(28/5):

[This note was reworded into something that badly muddled the point. This is clearly a usage recommendation, and those cannot be notes (see !discussion for more on this point and how these are handled). This note will be omitted from the FDIS.]

Modify 12.1(13):

NOTE 3   A default_expression or default_name appearing in a generic_formal_part is not evaluated during elaboration of the generic_formal_part; instead, it is evaluated when used. {However, the}[(The] usual visibility rules apply to any name used in a default{, with name resolution performed based on the location of the name within the generic_formal_part.}[: the denoted declaration therefore has to be visible at the place of the expression.)]

[“has to be”. As with 3.9.3, this is the point.]

Modify 12.5.1(28):

NOTE 2   If the formal has a discriminant_part, the actual can be either definite or indefinite. Otherwise, the actual {can only}[has to] be definite.

[“has to be”.]

Modify 13.11.4(33/5):

NOTE 1   A user-defined storage pool type that supports subpools can be implemented by extending the Root_Storage_Pool_With_Subpools type, and overriding the primitive subprograms Create_Subpool, Allocate_From_Subpool, and Deallocate_Subpool. Create_Subpool is expected to call Set_Pool_Of_Subpool before returning the subpool handle. To make use of such a pool, a user can declare an object of the type extension, {can }use it to define the Storage_Pool attribute of one or more access types, and then {can invoke}[call] Create_Subpool to obtain subpool handles associated with the pool.

[“use it” was highlighted here, without comment. “can” applies to all of these here, maybe we have to be explicit as above.]

Modify A.5.2(50/5):

["it is preferred", with the following comment: "Preferred by whom? If this is a covert recommendation, please rephrase so it expresses a statement of fact." This is clearly a usage recommendation, and those cannot be notes (see

will be omitted from the FDIS. We have partially reverted this wording to make the recommendation clear as there is no reason for it to be "covert". Note that the original wording also used "Portable applications should assume", but it not as clear that is an improvement over the rewording, so it was not changed.]

Modify A.16(131/5):

["delete it first" was highlighted here, without comment. Not sure what the complaint is. However, this is clearly a usage recommendation, and indeed the original wording used "should" as given above, which we have reverted to. Usage recommendations cannot be notes (see !discussion for more on this point and how these are handled). This note will be omitted from the FDIS.]

Modify C.3(29):

NOTE 1   The default treatment for an interrupt can be to keep the interrupt pending or to deliver it to an implementation-defined handler. Examples of actions that an implementation-defined handler {can}[is allowed to] perform include aborting the partition, ignoring ({that is}[i.e.], discarding occurrences of) the interrupt, or queuing one or more occurrences of the interrupt for possible later delivery when a user-defined handler is attached to that interrupt.

[“is allowed to”. See AI12-0453-1 for reasoning for "i.e." change.]

Modify D.3(20):

NOTE 3   {As described in C.3.1, a check is made whenever an interrupt is handled by one of the protected procedures of a protected object that its}[The] ceiling priority {is}[of a protected object has to be] in the Interrupt_Priority range[ if one of its procedures is to be used as an interrupt handler (see C.3)].

[“has to be”.]

Modify D.5.1(18/3):

NOTE 4   The rule for when Tasking_Error is raised for Set_Priority or Get_Priority is different from the rule for when Tasking_Error is raised on an entry call (see 9.5.3). In particular, [querying ]the priority of a completed or an abnormal task {can be queried}[is allowed,] so long as the task is not yet terminated, and [setting ]the priority of a task {can be set in}[is allowed for] any task state (including for terminated tasks).

[“is allowed” (twice).]

Modify H.3.2(9/2):

NOTE 1   {Because reaching an inspection point is considered an external interaction relative to the values of the inspectable variables, the}[The] implementation {cannot}[is not allowed to] perform “dead store elimination” on the last assignment to {such }a variable prior to {an inspection point}[a point where the variable is inspectable]. Thus an inspection point has the effect of an implicit read of each of its inspectable objects.

[“is not allowed”.]

Modify H.3.2(11):

NOTE 3   The identification of the mapping from source program objects to machine resources {can}[is allowed to] be in the form of an annotated object listing, in human-readable or tool-processable form.

[“is allowed to be”.]

The ISO editors flagged all of these phrases.

The ISO editors did not flag text that talks about rules given elsewhere. We should be allowed to say something like "The rules of this subclause require" or "The rules of 7.8 prevent" (although we should try to avoid words like require when possible).

Most of these notes do not make sense as simple statements of fact, since the point is that we (in this document) are requiring these facts. Otherwise, they would appear mysterious.

----

Some notes that the ISO editor's flagged defied useful rewording and do not appear in this AI. Instead, they have been removed from the FDIS.

Many of these are usage recommendations. That is, they tell Ada users something that they "should" do. Recommendations are explicitly banned from notes. Moreover, we tried some rewording as "almost recommendations" in an earlier ISO update, but ISO complained about "covert recommendations" in their most recent comments. Therefore, additional attempts at rewording are likely to be futile.

The best solution would be to create a new category, possibly "Usage Advice", and move all of these notes to that category. However, that requires care as the new wording would be normative (if unenforceable) so each note would have to be carefully examined for sloppy wording and minor untruths. Additionally, simply moving the notes that ISO flagged would potentially leave behind some additional notes that would fit well into the category. After all, all discussion aimed at Ada users has been jammed into notes in the RM, so there are many such notes. Deciding exactly which notes should be included in the new category (and the name for the category) is likely to take some time and discussion, so it is inappropriate at this point in the development of Ada 2022. We have gathered all of the currently known notes into a future Ada 2022 AI, and should plan to address this in a future Ada standard. Therefore, all of the "Usage Advice" notes will be left out of the FDIS (but will continue to appear in the RM as they currently are written).

There are a few notes in this category that do appear in this AI. These notes are ones that we previously tried (and failed) to reword to ISO's satisfaction. We are recommending to revert/modify some of that previous rewording to make the meaning clearer; in particular, using "should" where that best carries the meaning. There is no reason to make the notes in the RM hard to understand because of failed updates.

No ASIS effect.

These are just notes, no tests are needed.

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