[Ada] Import documentation from the RM for various runtime units

2019-08-19  Pierre-Marie de Rodat  <derodat@adacore.com>

gcc/ada/

	* libgnat/a-cgaaso.ads, libgnat/a-cgarso.ads,
	libgnat/a-cogeso.ads, libgnat/a-contai.ads,
	libgnat/a-locale.ads: Import documentation from the RM.

From-SVN: r274659

gcc/ada/ChangeLog

@@ -1,3 +1,9 @@
+2019-08-19  Pierre-Marie de Rodat  <derodat@adacore.com>
+
+	* libgnat/a-cgaaso.ads, libgnat/a-cgarso.ads,
+	libgnat/a-cogeso.ads, libgnat/a-contai.ads,
+	libgnat/a-locale.ads: Import documentation from the RM.
+
 2019-08-19  Jerome Guitton  <guitton@adacore.com>
 
 	* Makefile.rtl (system.o): New target to add generation of

gcc/ada/libgnat/a-cgaaso.ads

@@ -39,3 +39,16 @@ generic
 procedure Ada.Containers.Generic_Anonymous_Array_Sort
   (First, Last : Index_Type'Base);
 pragma Pure (Ada.Containers.Generic_Anonymous_Array_Sort);
+--  Reorders the elements of Container such that the elements are sorted
+--  smallest first as determined by the generic formal "<" operator provided.
+--  Any exception raised during evaluation of "<" is propagated.
+--
+--  The actual function for the generic formal function "<" is expected to
+--  return the same value each time it is called with a particular pair of
+--  element values. It should not modify Container and it should define a
+--  strict weak ordering relationship: irreflexive, asymmetric, transitive, and
+--  in addition, if x < y for any values x and y, then for all other values z,
+--  (x < z) or (z < y).  If the actual for "<" behaves in some other manner,
+--  the behavior of the instance of Generic_Anonymous_Array_Sort is
+--  unspecified. The number of times Generic_Anonymous_Array_Sort calls "<" is
+--  unspecified.

gcc/ada/libgnat/a-cgarso.ads

@@ -18,9 +18,19 @@ generic
    type Element_Type is private;
    type Array_Type is array (Index_Type range <>) of Element_Type;
 
-   with function "<" (Left, Right : Element_Type)
-      return Boolean is <>;
+   with function "<" (Left, Right : Element_Type) return Boolean is <>;
 
 procedure Ada.Containers.Generic_Array_Sort (Container : in out Array_Type);
-
 pragma Pure (Ada.Containers.Generic_Array_Sort);
+--  Reorders the elements of Container such that the elements are sorted
+--  smallest first as determined by the generic formal "<" operator provided.
+--  Any exception raised during evaluation of "<" is propagated.
+--
+--  The actual function for the generic formal function "<" is expected to
+--  return the same value each time it is called with a particular pair of
+--  element values. It should not modify Container and it should define a
+--  strict weak ordering relationship: irreflexive, asymmetric, transitive, and
+--  in addition, if x < y for any values x and y, then for all other values z,
+--  (x < z) or (z < y).  If the actual for "<" behaves in some other manner,
+--  the behavior of the instance of Generic_Array_Sort is unspecified. The
+--  number of times Generic_Array_Sort calls "<" is unspecified.

gcc/ada/libgnat/a-cogeso.ads

@@ -38,3 +38,19 @@ generic
 
 procedure Ada.Containers.Generic_Sort (First, Last : Index_Type'Base);
 pragma Pure (Ada.Containers.Generic_Sort);
+--  Reorders the elements of an indexable structure, over the range
+--  First .. Last, such that the elements are sorted in the ordering determined
+--  by the generic formal function Before; Before should return True if Left is
+--  to be sorted before Right. The generic formal Before compares the elements
+--  having the given indices, and the generic formal Swap exchanges the values
+--  of the indicated elements. Any exception raised during evaluation of Before
+--  or Swap is propagated.
+--
+--  The actual function for the generic formal function "<" is expected to
+--  return the same value each time it is called with a particular pair of
+--  element values. It should not modify Container and it should define a
+--  strict weak ordering relationship: irreflexive, asymmetric, transitive, and
+--  in addition, if x < y for any values x and y, then for all other values z,
+--  (x < z) or (z < y).  If the actual for "<" behaves in some other manner,
+--  the behavior of the instance of Generic_Sort is unspecified. The number of
+--  times Generic_Sort calls "<" is unspecified.

gcc/ada/libgnat/a-contai.ads

@@ -17,8 +17,12 @@ package Ada.Containers is
    pragma Pure;
 
    type Hash_Type is mod 2**32;
+   --  Represents the range of the result of a hash function
+
    type Count_Type is range 0 .. 2**31 - 1;
+   --  Represents the (potential or actual) number of elements of a container
 
    Capacity_Error : exception;
+   --  Raised when the capacity of a container is exceeded
 
 end Ada.Containers;

gcc/ada/libgnat/a-locale.ads

@@ -19,18 +19,34 @@ package Ada.Locales is
    pragma Preelaborate (Locales);
    pragma Remote_Types (Locales);
 
+   --  A locale identifies a geopolitical place or region and its associated
+   --  language, which can be used to determine other
+   --  internationalization-related characteristics. The active locale is the
+   --  locale associated with the partition of the current task.
+
    type Language_Code is new String (1 .. 3)
       with Dynamic_Predicate =>
          (for all E of Language_Code => E in 'a' .. 'z');
+   --  Lower-case string representation of an ISO 639-3 alpha-3 code that
+   --  identifies a language.
 
    type Country_Code is new String (1 .. 2)
       with Dynamic_Predicate =>
          (for all E of Country_Code => E in 'A' .. 'Z');
+   --  Upper-case string representation of an ISO 3166-1 alpha-2 code that
+   --  identifies a country.
 
    Language_Unknown : constant Language_Code := "und";
    Country_Unknown  : constant Country_Code := "ZZ";
 
    function Language return Language_Code;
+   --  Returns the code of the language associated with the active locale. If
+   --  the Language_Code associated with the active locale cannot be determined
+   --  from the environment, then Language returns Language_Unknown.
+
    function Country return Country_Code;
+   --  Returns the code of the country associated with the active locale. If
+   --  the Country_Code associated with the active locale cannot be determined
+   --  from the environment, then Country returns Country_Unknown.
 
 end Ada.Locales;