Re: Is the Documentation In a spec File Usually Enough For You ?

[Brad Moore <bmoore.ada@gmail.com>]

It should also be mentioned that with Ada 2012, the addition of contracts helps also aid to reader of a spec understand what a subprogram does, and how it was intended to be used by the author. 

A problem with documentation is that it can become stale if not maintained, whereas the contracts are assertions in the code and thus tend to be more accurate. 

A designer of a package should consider, for example, what pre and post conditions should be applied to the subprograms of that package. The addition of contracts tends to simplify the documentation that is needed.

As an example, in the standard package
Ada.Locales, there is;

   type Country_Code is new String (1 .. 2)
      with Dynamic_Predicate =>
         (for all E of Country_Code => E in 'A' .. 'Z');

 function Country return Country_Code;

If we didn't have the contract for Dynamic_Predicate on the Country_Code type, 
we would need to document that the function Country returns a 2 character string where all the characters of the string consist of capital letters from A to Z inclusive.  

With the contract, this doesn't need to be documented, and the contract is more concise for the reader than having to read a full paragraph of text. Further, anywhere the Country_Code result is used in the user's program, it is clear that the contract holds, since it is a property of the type.

If the implementation changes in a way that breaks the contracts, then this tends to get caught, and either the implementation is adjusted to meet the contracts, or the contracts are adjusted to meet the implementation. Generally one tries to avoid making changes to contracts, particularly if there are existing users of those contracts.

Brad