1

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?

Rick
  • 680
  • 1
  • 7
  • 20
  • 2
    Almost all subprograms from Standard Library are very well documented, together with exceptions and return values (for example Ada.Strings.Fixed.Index returns 0 if Substring is not present in String). As such I don't see what is the problem. (implementation defined subprograms have to be documented in user guide (or reference); in case of gnat they are documented gnat pro user guide (or reference) [don't remember now which one]) – darkestkhan May 29 '14 at 11:02
  • Can you give an example of a language-defined subprogram where you've found the RM's description to be inadequate? I'm asking because maybe the description really is there and you've just had trouble finding it (there are some places where the description's location isn't in the obvious place, such as some I/O operations). – ajb May 29 '14 at 15:22
  • darkestkhan, the [GNAT library description in the FSF version of the GNAT RM](https://gcc.gnu.org/onlinedocs/gnat_rm/The-GNAT-Library.html) is very sparse, the documentation is in the source files! (as Herr_Doktor wants) – Simon Wright May 29 '14 at 16:43
  • Just one example is the ADS file Ada.Containers.Doubly_Linked_Lists. there is no comment in there, just the definitions for types, subprograms etc. Looks to me like the designers assume that everybody has the same understanding for every identifier there, but what if not and people assume different behaviour. Compare it for instance with Ada.Containers.Hashed_Maps which at least contains some comments that explains functionality. To me as a newcomer, this leaves much to guesswork – Rick May 30 '14 at 03:00

2 Answers2

3

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!)

Simon Wright
  • 25,108
  • 2
  • 35
  • 62
3

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.

Jacob Sparre Andersen
  • 6,733
  • 17
  • 22
  • Individual implementations aren't even required to provide source files for the standard library. – ajb May 30 '14 at 14:47
  • 1
    Ok, this is certainly more than in most header files I have seen and presumably this seems to be sufficient for the people who implement compilers and standard libraries. It's written in a very abstract and hard to understand style but I guess the formal definitions in the annotated manual are indeed what implementers need. It's not very helpful for a newcommer to Ada but that wasn't my question either (although thinking about it, it would be a great topic for a book). – Rick May 31 '14 at 00:53
  • 1
    My main concern was how are libraries guaranteed to implement the same semantics with nothing but the interface specifications, but it seems the annotated manual pretty much answers that question. – Rick May 31 '14 at 00:54