Version 1.1 of ais/ai-00425.txt

Unformatted version of ais/ai-00425.txt version 1.1
Other versions for file ais/ai-00425.txt

!standard M (1)          05-04-06 AI95-00425/01
!standard M.1(1)
!standard M.2(1)
!standard M.3(1)
!class presentation 05-04-06
!comment This is in the Amendment (AARM), but not yet approved.
!status Amendment 200Y 05-04-06
!status work item 05-04-06
!status received 05-04-06
!priority Medium
!difficulty Easy
!subject Organization of Annex M
!summary
Annex M needs a better organization.
!question
The purpose of Annex M is to list the documentation requirements for an Ada implementation, but it is is poorly organized for this purpose.
First, the title is "Implementation-Defined Characteristics". But this is really about summarizing the documentation requirements, which cover more than just implementation-defined characteristics.
For instance, some Documentation Requirements are mixed in with the implementation-defined characteristics, and others are just left out. It seems that Documentation Requirements are different than implementation-defined characteristics - some are more about characteristics of the target environment, for instance. Indeed, the requirement to document implementation-defined items is in fact a Documentation Requirement.
Annex M is also very vague about some characteristics. For instance, M(54) requires documentation of "Implementation-defined aspects of storage pools." This sounds very scary. It turns out, however, that it is only a requirement to document the alignments required for a user-defined storage pool, and a requirement to document the behavior of the standard storage pool (all of the other issues were covered by other bullets in the list). That's a lot less scary.
For another example, the Annex simply says that whether Implementation Advice is followed should be documented, leaving both the implementer and reader to look up all of the advice. The reader cannot tell if the information given by the implementer is complete without referring to the entire Standard.
!recommendation
Retitle Annex M as "Summary of Documentation Requirements"; then split it into three subclauses: M.1 Documentation Requirements; M.2 Implementation-Defined Characteristics; and M.3 Implementation Advice. Add summaries of all of the Documentation Requirements and Implementation Advice to the appropriate sections.
Remove any Documentation Requirements from the list of Implementation-Defined Characteristics, and improve summaries that are too vague.
!wording
(See corrigendum.)
!discussion
Some Documentation Requirements echo implementation-defined characteristics mentioned earlier in a clause. In this case, we only include the Documentation Requirements in the Annex, as these are usually more detailed.
On the other hand, Implementation Advice which is similar to implementation-defined characteristics or Documentation Requirements is repeated. Usually, such Advice is adding additional suggestions to existing requirements, and it is necessary to document the suggestions as well as the requirements.
Note that the detailed summaries are generated semi-automatically from the text of the AARM, and thus are not included here.
!corrigendum M(01)
Replace the paragraph:
The Ada language allows for certain machine dependences in a controlled manner. Each Ada implementation must document all implementation-defined characteristics.
by:
The Ada language allows for certain target machine dependences in a controlled manner. Each Ada implementation must document many characteristics and properties of the target system. This International Standard contains specific documentation requirements. In addition, many characteristics that require documentation are identified throughout this International Standard as being implementation defined. Finally, this International Standard requires documentation of whether implementation advice is followed. The following clauses provide summaries of these documentation requirements.
!corrigendum M.1(01)
Insert new clause:
In addition to implementation-defined characteristics, each Ada implementation must document various properties of the implementation:
!corrigendum M.2(01)
Insert new clause:
The Ada language allows for certain machine dependences in a controlled manner. Each Ada implementation must document all implementation-defined characteristics:
!corrigendum M.3(01)
Insert new clause:
This International Standard sometimes gives advice about handling certain target machine dependences. Each Ada implementation must document whether that advice is followed:
!ACATS test
None needed.
!appendix

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


Questions? Ask the ACAA Technical Agent