Why is there no commented version of the Ada Standard Library

Question

I am a huge fan of source code comments but the comments in the Ada standard library are spartan at best. It is my understanding that the interface of the library is defined with the language definition, but the implementation is left to the compiler manufacturer. I often wondered how they do it, since the pure function names, parameters, and other definitions as I see them in the manual often don't explain what exactly the respective subprograms do and leave much to interpretation. I would expect some documentation along the line of the QT library.

Why is it there no definition of the library with extensive comments for every function?

Answer 1

It sounds like you are looking for the documentation in the wrong place.

The Ada standard library is described in great detail in the standard (the Ada Reference Manual) - and in even greater detail in the Annotated Ada Reference Manual.

The source files of the individual implementations of the Ada standard library are not the documentation of how the standard library should work.

Answer 2

For an example, the ARM section A.18.5 for Ada.Containers.Hashed_Maps says in paragraph 1 - which would normally be referred to as "A.18.5 (1)” -

The generic library package Containers.Hashed_Maps has the following declaration:

so I guess that implementors have read this as an instruction.

In the case of Hashed_Maps, you’ll see at A.18.5 (46) a link to A.18.4, which describes the common semantics of Maps; and Length, for example, is at (25).

GPS GPL from AdaCore Help > GNAT has links to a local copy of the ARM (GPS GPL 2014 only goes up to ARM2005); I don’t know what the Debian version does.

(This is how it is; that’s not to deny you have a point about how it might be better!)