search

pat-rogers / Ada-202x-WG9-Informal-Review

This is the place for WG 9 members to submit informal comments on the 202x source document. (This is not the formal ballot that WG 9 will hold later in the process.)
0 stars 0 forks source link

(many paragraphs) Examples need lead-ins to be consistent #97

Open sttaft opened 3 years ago

sttaft commented 3 years ago

For essentially all features from Ada 95 and Ada 2005, if there is an "Examples" section there are one or more lead-ins that introduce each set of examples. This practice seems to have disappeared for newer features. It makes for an inconsistent treatment of examples. I suggest we add "lead-ins" where they are missing.

3.2.4 Subtype Predicates

Preceding paragraph (39/4):

Examples of predicates applied to scalar types:

4.1.5 User-Defined References

Preceding paragraph (9/3):

Examples of the specification and use of generalized references:

4.1.6 User-Defined Indexing Preceding paragraph (19/3):

Examples of the specification and use of generalized indexing:

4.2.1 User-Defined Literals Preceding paragraph (18/5):

Examples of the specification and use of user-defined literals:

4.3.4 Delta Aggregates (22/5)

{AI12-0127-1} [Simple]{Examples of} use {of delta aggregates} in a postcondition:

(25/5)

{AI12-0127-1} {AI12-0324-1} {AI12-0379-1} {AI12-0386-1} {Examples where t}[T]he base expression [can be]{is} nontrivial:

(29/5)

{AI12-0127-1} {AI12-0379-1} {Examples where t}[T]he base expression [may also be]{is} class-wide:

4.3.5 Container Aggregates

(54/5)

{AI12-0212-1} [Declarations of]_{Examples of specifying the Aggregate aspect for a} Set_Type, {a} Map_Type, and {a} VectorType:

(67/5) -- italicizing is the only change:

{AI12-0212-1} _Examples of container aggregates for Set_Type, Map_Type, and VectorType:

4.5.7 Conditional Expressions Preceding paragraph (22/5):

_Example of use of an ifexpression:

Preceding paragraph (23.5):

_Example of use of a caseexpression:

4.5.8 Quantified Expressions

(10/3)

{AI05-0176-1} [The]{Example of a quantified expression as a postcondition for a sorting routine on an array A with an index subtype T[ can be written]:

(12/3)

{AI05-0176-1} [The]{Example of use of a quantified expression as an assertion that a positive number is composite (as opposed to prime)[ can be written]:

4.5.9 Declare Expressions

(11/5)

{AI12-0236-1} [The]{Example of use of a declare expression as a postcondition for Ada.Containers.Vectors."&" (see A.18.2)[ could have been written]:

4.5.10 Reduction Expressions

(35/5)

{AI12-0262-1} {Example of a}[A]n expression function that returns its result as a [R]{r}eduction [E]{e}xpression:

(37/5)

{AI12-0262-1} [An] {Example of a reduction} expression [function] that computes the Sine of X using a Taylor expansion:

(39/5)

{AI12-0262-1} {AI12-0379-1} [A]{Example of a} reduction expression that outputs the sum of squares:

(41/5)

{AI12-0262-1} {AI12-0379-1} [An] {Example of a reduction} expression [function]{used} to compute the value of Pi:

(43/5)

{AI12-0242-1} {Example of a reduction expression used to c}[C]alculate the sum of elements of an array of integers:

(45/5)

{AI12-0242-1} {Example of a reduction expression used to d}[D]etermine if all elements in a two-dimensional array of booleans are set to true:

(47/5)

{AI12-0242-1} {Example of a reduction expression used to c}[C]alculate the minimum value of an array of integers in parallel:

(49/5)

{AI12-0312-1} [A]{Example of a} parallel reduction expression used to calculate the mean of the elements of a two-dimensional array of subtype Matrix (see 3.6) that are greater than 100.0:

5.2.1 Target Name Symbols

Preceding paragraph (6/5):

Examples of the use of target name symbols:

5.5.2 Generalized Loop Iteration

Preceding paragraph (15/5):

Example of a parallel generalized loop over an array:

16/3 -- only change is to italicize:

{AI05-0268-1} For examples of use of generalized iterators, see A.18.33 and the corresponding container packages in A.18.2 and A.18.3.

5.5.3 Procedural Iterators

(30/5) -- only change is to italicize:

{AI12-0189-1} {AI12-0379-1} _Example of iterating over a map from My_Key_Type to My_ElementType (see A.18.4):

(34/5) -- only change is to italicize:

{AI12-0189-1} Example of iterating over the environment variables (see A.17):

5.6.1 Parallel Block Statements

Preceding paragraph (4/5):

Example of a parallel block used to walk a binary tree in parallel:

Preceding paragraph 5/5):

Example of a parallel block used to search two halves of a string in parallel:

6.5.1 Nonreturning Subprograms

Preceding paragraph (10/3):

_Example of a specification of a NoReturn aspect:

6.7 Null Procedures

Preceding paragraph (6/2):

Example of the declaration of a null procedure:

6.8 Expression Functions

Preceding paragraph (9/3):

Example of an expression function:

7.3.2 Type Invariants

(25/5)

{AI12-0312-1} [A]{Example of a} work scheduler where only urgent work can be scheduled for weekends:

8.3.1 Overriding Indicators

(9/2)

{AI95-00433-01} [The use of overridingindicators allows the detection of errors at compile-time that otherwise might not be detected at all. For instance, we might declare]{Example of use of an overriding indicator when declaring} a security queue derived from the Queue interface of 3.9.4[ as]:_

(16/2) -- Italicize the following (and make one addition):

The first four subprogram declarations guarantee that these subprograms will override the four subprograms inherited from the Queue interface. A misspelling in one of these subprograms will be detected {at compile time} by the implementation. Conversely, the declaration of Arrest guarantees that this is a new operation.

10.1.2 Context Clauses - With Clauses

Preceding paragraph (24/2):

Examples of use of with clauses, limited with clauses, and private with clauses:

(31/2) -- Italicize the following:

{AI95-00433-01} _The limited_with_clause may be used to support mutually dependent abstractions that are split across multiple packages. In this case, an employee is assigned to a department, and a department has a manager who is an employee. If a withclause with the reserved word private appears on one library unit and mentions a second library unit, it provides visibility to the second library unit, but restricts that visibility to the private part and body of the first unit. The compiler checks that no use is made of the second unit in the visible part of the first unit.

10.1.3 Subunits of Compilation Units

(19)

{Example that defines} [The] package Parent [is first written] without subunits:

(22)

{Example showing how t}[T]he body of procedure Inner may be turned into a subunit by rewriting the package body as follows (with the declaration of Parent remaining the same):

12.5.5 Formal Interface Types

Preceding paragraph (5/2):

Example of the use of a generic with a formal interface type, to establish a standard interface that all tasks need to implement so they can be managed appropriately by an application-specific scheduler.

(7/2) -- delete this paragraph:

{AI95-00433-01} This generic allows an application to establish a standard interface that all tasks need to implement so they can be managed appropriately by an application-specific scheduler.

A.4.2 Package Strings.Maps

Preceding paragraph (67):

_Example of use of Strings.Maps.ToMapping:

A.10.8 Input-Output for Integer Types

Preceding paragraph (26/3):

_Examples of use of an instantiation of Text_IO.IntegerIO:

A.10.9 Input-Output for Real Types

Preceding paragraph (41):

_Examples of use of an instantiation of Text_IO.FloatIO:

F.3.2 Edited Output Generation

(71)

{Examples of use of edited output; i}[I]n the result string values shown below, 'b' represents the space character[.]{:}

ARG-Editor commented 3 years ago

Tucker was nice enough to provide this in AI form; that has now been assigned AI12-0429-1.