doc: removed deprecated function descriptions + fixes

zerothi · zerothi · commit 5c151475f533 · 2023-02-27T22:05:08.000+01:00
Now the descriptions of the deprecated functions
primarily exists in the favored functions.

Added more cross-links in the documentation.

Several typos are corrected and codifying
constants here and there.

Signed-off-by: Nick Papior &lt;nickpapior@gmail.com&gt;
diff --git a/docs/man-openmpi/man3/MPI_Address.3.rst b/docs/man-openmpi/man3/MPI_Address.3.rst
@@ -50,40 +50,6 @@ DESCRIPTION
 Note that use of this routine is *deprecated* as of MPI-2. Please use
 :ref:`MPI_Get_address` instead.
 
-The address of a location in memory can be found by invoking this
-function. Returns the (byte) address of location.
-
-Example: Using :ref:`MPI_Address` for an array.
-
-.. code-block:: fortran
-
-   REAL A(100,100)
-
-   INTEGER I1, I2, DIFF
-   CALL MPI_ADDRESS(A(1,1), I1, IERROR)
-   CALL MPI_ADDRESS(A(10,10), I2, IERROR)
-   DIFF = I2 - I1
-   ! The value of DIFF is 909*sizeof(real)
-   !the values of I1 and I2 are implementation dependent.
-
-
-NOTES
------
-
-This routine is provided for both Fortran and C programmers and may be
-useful when writing portable code. In the current release, the address
-returned by this routine will be the same as that produced by the C ``&``
-operator.
-
-C users may be tempted to avoid using :ref:`MPI_Address` and rely on the
-availability of the address operator &. Note, however, that &
-cast-expression is a pointer, not an address. ANSI C does not require
-that the value of a pointer (or the pointer cast to int) be the absolute
-address of the object pointed at although this is commonly the case.
-Furthermore, referencing may not have a unique definition on machines
-with a segmented address space. The use of :ref:`MPI_Address` to "reference" C
-variables guarantees portability to such machines as well.
-
 
 ERRORS
 ------
diff --git a/docs/man-openmpi/man3/MPI_Attr_delete.3.rst b/docs/man-openmpi/man3/MPI_Attr_delete.3.rst
@@ -50,27 +50,6 @@ Note that use of this routine is *deprecated* as of MPI-2, and was
 *deleted* in MPI-3. Please use :ref:`MPI_Comm_delete_attr`. This function does
 not have a mpi_f08 binding.
 
-Delete attribute from cache by key. This function invokes the attribute
-delete function delete_fn specified when the keyval was created. The
-call will fail if the delete_fn function returns an error code other
-than MPI_SUCCESS.
-
-Whenever a communicator is replicated using the function :ref:`MPI_Comm_dup`,
-all callback copy functions for attributes that are currently set are
-invoked (in arbitrary order). Whenever a communicator is deleted using
-the function :ref:`MPI_Comm_free`, all callback delete functions for attributes
-that are currently set are invoked.
-
-
-NOTES
------
-
-Note that it is not defined by the MPI standard what happens if the
-delete_fn callback invokes other MPI functions. In Open MPI, it is not
-valid for delete_fn callbacks (or any of their children) to add or
-delete attributes on the same object on which the delete_fn callback is
-being invoked.
-
 
 ERRORS
 ------
diff --git a/docs/man-openmpi/man3/MPI_Attr_get.3.rst b/docs/man-openmpi/man3/MPI_Attr_get.3.rst
@@ -54,12 +54,6 @@ Note that use of this routine is *deprecated* as of MPI-2, and was
 *deleted* in MPI-3. Please use :ref:`MPI_Comm_get_attr`. This function does not
 have a mpi_f08 binding.
 
-Retrieves attribute value by key. The call is erroneous if there is no
-key with value keyval. On the other hand, the call is correct if the key
-value exists, but no attribute is attached on comm for that key; in such
-case, the call returns flag = false. In particular MPI_KEYVAL_INVALID is
-an erroneous key value.
-
 
 ERRORS
 ------
diff --git a/docs/man-openmpi/man3/MPI_Attr_put.3.rst b/docs/man-openmpi/man3/MPI_Attr_put.3.rst
@@ -51,31 +51,6 @@ Note that use of this routine is *deprecated as of MPI-2, and* was
 deleted in MPI-3. Please use :ref:`MPI_Comm_set_attr`. This function does not
 have a mpi_f08 binding.
 
-:ref:`MPI_Attr_put` stores the stipulated attribute value attribute_val for
-subsequent retrieval by :ref:`MPI_Attr_get`. If the value is already present,
-then the outcome is as if :ref:`MPI_Attr_delete` was first called to delete the
-previous value (and the callback function delete_fn was executed), and a
-new value was next stored. The call is erroneous if there is no key with
-value keyval; in particular MPI_KEYVAL_INVALID is an erroneous key
-value. The call will fail if the delete_fn function returned an error
-code other than MPI_SUCCESS.
-
-
-NOTES
------
-
-Values of the permanent attributes MPI_TAG_UB, MPI_HOST, MPI_IO, and
-MPI_WTIME_IS_GLOBAL may not be changed.
-
-The type of the attribute value depends on whether C or Fortran is being
-used. In C, an attribute value is a pointer (``void *``); in Fortran, it is
-a single integer (not a pointer, since Fortran has no pointers and there
-are systems for which a pointer does not fit in an integer, e.g., any
-32-bit address system that uses 64 bits for Fortran DOUBLE PRECISION).
-
-If an attribute is already present, the delete function (specified when
-the corresponding keyval was created) will be called.
-
 
 ERRORS
 ------
diff --git a/docs/man-openmpi/man3/MPI_Comm_create_keyval.3.rst b/docs/man-openmpi/man3/MPI_Comm_create_keyval.3.rst
@@ -131,4 +131,5 @@ ERRORS
 
 .. include:: ./ERRORS.rst
 
-.. seealso:: :ref:`MPI`
+.. seealso::
+   * :ref:`MPI_Comm_free_keyval`
diff --git a/docs/man-openmpi/man3/MPI_Comm_delete_attr.3.rst b/docs/man-openmpi/man3/MPI_Comm_delete_attr.3.rst
@@ -64,7 +64,8 @@ DESCRIPTION
 :ref:`MPI_Comm_delete_attr` deletes an attribute from cache by key. This
 function invokes the attribute delete function ``delete_fn`` specified
 when the ``comm_keyval`` was created. The call will fail if the
-``delete_fn`` function returns an error code other than MPI_SUCCESS.``
+``delete_fn`` function returns an error code other than ``MPI_SUCCESS``.
+
 Whenever a communicator is replicated using the function
 :ref:`MPI_Comm_dup`, all callback copy functions for attributes that are
 currently set are invoked (in arbitrary order). Whenever a communicator
diff --git a/docs/man-openmpi/man3/MPI_Comm_free_keyval.3.rst b/docs/man-openmpi/man3/MPI_Comm_free_keyval.3.rst
@@ -81,3 +81,6 @@ Key values are global (they can be used with any and all communicators).
 ERRORS
 ------
 .. include:: ./ERRORS.rst
+
+.. seealso::
+   * :ref:`MPI_Comm_create_keyval`
diff --git a/docs/man-openmpi/man3/MPI_Comm_get_attr.3.rst b/docs/man-openmpi/man3/MPI_Comm_get_attr.3.rst
@@ -69,7 +69,7 @@ DESCRIPTION
 erroneous if there is no key with value *keyval*. On the other hand, the
 call is correct if the key value exists, but no attribute is attached on
 *comm* for that key; in that case, the call returns *flag* = false. In
-particular, MPI_KEYVAL_INVALID is an erroneous key value.
+particular, ``MPI_KEYVAL_INVALID`` is an erroneous key value.
 
 This function replaces :ref:`MPI_Attr_get`, the use of which is deprecated. The
 C binding is identical. The Fortran binding differs in that
diff --git a/docs/man-openmpi/man3/MPI_Comm_get_errhandler.3.rst b/docs/man-openmpi/man3/MPI_Comm_get_errhandler.3.rst
@@ -65,7 +65,20 @@ with a communicator. This call is identical to :ref:`MPI_Errhandler_get`, the
 use of which is deprecated.
 
 
+Returns in errhandler (a handle to) the error handler that is currently
+associated with communicator ``comm``.
+
+**Example:** A library function may register at its entry point the
+current error handler for a communicator, set its own private error
+handler for this communicator, and restore before exiting the previous
+error handler.
+
+
 ERRORS
 ------
 
 .. include:: ./ERRORS.rst
+
+.. seealso::
+   * :ref:`MPI_Comm_create_errhandler`
+   * :ref:`MPI_Comm_set_errhandler`
diff --git a/docs/man-openmpi/man3/MPI_Comm_set_attr.3.rst b/docs/man-openmpi/man3/MPI_Comm_set_attr.3.rst
@@ -67,11 +67,11 @@ DESCRIPTION
 :ref:`MPI_Comm_set_attr` stores the stipulated attribute value *attribute_val*
 for subsequent retrieval by :ref:`MPI_Comm_get_attr`. If the value is already
 present, then the outcome is as if :ref:`MPI_Comm_delete_attr` was first called
-to delete the previous value (and the callback function delete_fn was
+to delete the previous value (and the callback function ``delete_fn`` was
 executed), and a new value was next stored. The call is erroneous if
 there is no key with value *comm_keyval*; in particular
-MPI_KEYVAL_INVALID is an erroneous key value. The call will fail if the
-delete_fn function returned an error code other than MPI_SUCCESS.
+``MPI_KEYVAL_INVALID`` is an erroneous key value. The call will fail if the
+delete_fn function returned an error code other than ``MPI_SUCCESS``.
 
 This function replaces :ref:`MPI_Attr_put`, the use of which is deprecated. The
 C binding is identical. The Fortran binding differs in that
@@ -96,8 +96,8 @@ length of the declared integer in bytes.
 NOTES
 -----
 
-Values of the permanent attributes MPI_TAG_UB, MPI_HOST, MPI_IO, and
-MPI_WTIME_IS_GLOBAL may not be changed.
+Values of the permanent attributes ``MPI_TAG_UB``, ``MPI_HOST``, ``MPI_IO``, and
+``MPI_WTIME_IS_GLOBAL`` may not be changed.
 
 The type of the attribute value depends on whether C or Fortran is being
 used. In C, an attribute value is a pointer (``void *``); in Fortran, it is
diff --git a/docs/man-openmpi/man3/MPI_Comm_set_errhandler.3.rst b/docs/man-openmpi/man3/MPI_Comm_set_errhandler.3.rst
@@ -70,3 +70,7 @@ ERRORS
 ------
 
 .. include:: ./ERRORS.rst
+
+.. seealso::
+   * :ref:`MPI_Comm_create_errhandler`
+   * :ref:`MPI_Comm_get_errhandler`
diff --git a/docs/man-openmpi/man3/MPI_Errhandler_get.3.rst b/docs/man-openmpi/man3/MPI_Errhandler_get.3.rst
@@ -49,14 +49,6 @@ DESCRIPTION
 Note that use of this routine is *deprecated* as of MPI-2. Please use
 :ref:`MPI_Comm_get_errhandler` instead.
 
-Returns in errhandler (a handle to) the error handler that is currently
-associated with communicator comm.
-
-**Example:** A library function may register at its entry point the
-current error handler for a communicator, set its own private error
-handler for this communicator, and restore before exiting the previous
-error handler.
-
 
 ERRORS
 ------
diff --git a/docs/man-openmpi/man3/MPI_Get_address.3.rst b/docs/man-openmpi/man3/MPI_Get_address.3.rst
@@ -65,17 +65,32 @@ Example: Using :ref:`MPI_Get_address` for an array.
 
 .. code-block:: fortran
 
-   EAL A(100,100)
+   REAL A(100,100)
        INTEGER I1, I2, DIFF
        CALL MPI_GET_ADDRESS(A(1,1), I1, IERROR)
        CALL MPI_GET_ADDRESS(A(10,10), I2, IERROR)
        DIFF = I2 - I1
    ! The value of DIFF is 909*sizeofreal; the values of I1 and I2 are
    ! implementation dependent.
 
+
 NOTES
 -----
 
+This routine is provided for both Fortran and C programmers and may be
+useful when writing portable code. In the current release, the address
+returned by this routine will be the same as that produced by the C ``&``
+operator.
+
+C users may be tempted to avoid using :ref:`MPI_Get_address` and rely on the
+availability of the address operator ``&``. Note, however, that &
+cast-expression is a pointer, not an address. ANSI C does not require
+that the value of a pointer (or the pointer cast to int) be the absolute
+address of the object pointed at although this is commonly the case.
+Furthermore, referencing may not have a unique definition on machines
+with a segmented address space. The use of :ref:`MPI_Get_address` to "reference" C
+variables guarantees portability to such machines as well.
+
 Current Fortran MPI codes will run unmodified and will port to any
 system. However, they may fail if ``addresses`` larger than 2^32 - 1 are
 used in the program. New codes should be written so that they use the
@@ -84,6 +99,7 @@ new functions. This provides compatibility with C and avoids errors on
 (slightly) rewritten to port to old Fortran 77 environments that do not
 support KIND declarations.
 
+
 ERRORS
 ------
 
diff --git a/docs/man-openmpi/man3/MPI_Keyval_create.3.rst b/docs/man-openmpi/man3/MPI_Keyval_create.3.rst
@@ -59,7 +59,7 @@ allocated, the key value can be used to associate attributes and access
 them on any locally defined communicator.
 
 The copy_fn function is invoked when a communicator is duplicated by
-:ref:`MPI_COMM_DUP`. copy_fn should be of type MPI_Copy_function, which is
+:ref:`MPI_Comm_dup`. copy_fn should be of type MPI_Copy_function, which is
 defined as follows:
 
 .. code-block:: c
@@ -158,3 +158,4 @@ ERRORS
 .. seealso::
    * :ref:`MPI_Keyval_free`
    * :ref:`MPI_Comm_create_keyval`
+   * :ref:`MPI_Comm_free_keyval`
diff --git a/docs/man-openmpi/man3/MPI_Keyval_free.3.rst b/docs/man-openmpi/man3/MPI_Keyval_free.3.rst
@@ -48,21 +48,6 @@ DESCRIPTION
 Note that use of this routine is *deprecated* as of MPI-2. Please use
 :ref:`MPI_Comm_free_keyval` instead.
 
-Frees an extant attribute key. This function sets the value of keyval to
-MPI_KEYVAL_INVALID. Note that it is not erroneous to free an attribute
-key that is in use, because the actual free does not transpire until
-after all references (in other communicators on the process) to the key
-have been freed. These references need to be explicitly freed by the
-program, either via calls to :ref:`MPI_Attr_delete` that free one attribute
-instance, or by calls to :ref:`MPI_Comm_free` that free all attribute instances
-associated with the freed communicator.
-
-
-NOTE
-----
-
-Key values are global (they can be used with any and all communicators).
-
 
 ERRORS
 ------
@@ -71,4 +56,5 @@ ERRORS
 
 .. seealso::
    * :ref:`MPI_Keyval_create`
+   * :ref:`MPI_Comm_create_keyval`
    * :ref:`MPI_Comm_free_keyval`
diff --git a/docs/man-openmpi/man3/MPI_Type_create_hindexed.3.rst b/docs/man-openmpi/man3/MPI_Type_create_hindexed.3.rst
@@ -2,8 +2,88 @@
 
 MPI_Type_create_hindexed
 ========================
-    .. include_body
 
-.. include:: ../man3/MPI_Type_indexed.3.rst
-    :start-after: .. include_body
+.. include_body
 
+:ref:`MPI_Type_create_hindexed` - Creates an indexed datatype with offsets in bytes.
+
+
+SYNTAX
+------
+
+
+C Syntax
+^^^^^^^^
+
+.. code-block:: c
+
+   #include <mpi.h>
+
+   int MPI_Type_create_hindexed(int count, int *array_of_blocklengths,
+        MPI_Aint *array_of_displacements, MPI_Datatype oldtype,
+        MPI_Datatype *newtype)
+
+
+Fortran Syntax
+^^^^^^^^^^^^^^
+
+.. code-block:: fortran
+
+   INCLUDE 'mpif.h'
+   MPI_TYPE_CREATE_HINDEXED(COUNT, ARRAY_OF_BLOCKLENGTHS,
+             ARRAY_OF_DISPLACEMENTS, OLDTYPE, NEWTYPE, IERROR)
+       INTEGER COUNT, ARRAY_OF_BLOCKLENGTHS(*)
+       INTEGER ARRAY_OF_DISPLACEMENTS(*), OLDTYPE, NEWTYPE
+       INTEGER IERROR
+
+
+INPUT PARAMETERS
+----------------
+* ``count``: Number of blocks -- also number of entries in array_of_displacements and array_of_blocklengths (integer).
+* ``array_of_blocklengths``: Number of elements in each block (array of nonnegative integers).
+* ``array_of_displacements``: Byte displacement of each block (C: array of *MPI_Aint*, Fortran: array of integer).
+* ``oldtype``: Old datatype (handle).
+
+OUTPUT PARAMETERS
+-----------------
+* ``newtype``: New datatype (handle).
+* ``ierror``: Fortran only: Error status (integer).
+
+DESCRIPTION
+-----------
+
+The function is identical to :ref:`MPI_Type_indexed`, except that block
+displacements in ``array_of_displacements`` are specified in bytes, rather
+than in multiples of the ``oldtype`` extent.
+
+Assume that oldtype has type map
+
+::
+
+       {(type(0), disp(0)), ..., (type(n-1), disp(n-1))},
+
+with extent ex. Let B be the ``array_of_blocklength`` argument and D be the
+``array_of_displacements`` argument. The newly created datatype has
+
+::
+
+   n x S^count-1
+       (i=0)        B[i]  entries:
+
+     {(type(0), disp(0) + D[0]),...,(type(n-1), disp(n-1) + D[0]),...,
+     (type(0), disp(0) + (D[0] + B[0]-1)* ex),...,
+     type(n-1), disp(n-1) + (D[0]+ B[0]-1)* ex),...,
+     (type(0), disp(0) + D[count-1]),...,(type(n-1), disp(n-1) + D[count-1]),...,
+     (type(0), disp(0) +  D[count-1] + (B[count-1] -1)* ex),...,
+     (type(n-1), disp(n-1) + D[count-1] + (B[count-1] -1)* ex)}
+
+
+ERRORS
+------
+
+.. include:: ./ERRORS.rst
+
+.. seealso::
+   * :ref:`MPI_Type_create_struct`
+   * :ref:`MPI_Type_create_hvector`
+   * :ref:`MPI_Type_indexed`
diff --git a/docs/man-openmpi/man3/MPI_Type_create_hvector.3.rst b/docs/man-openmpi/man3/MPI_Type_create_hvector.3.rst
diff --git a/docs/man-openmpi/man3/MPI_Type_hindexed.3.rst b/docs/man-openmpi/man3/MPI_Type_hindexed.3.rst
diff --git a/docs/man-openmpi/man3/MPI_Type_hvector.3.rst b/docs/man-openmpi/man3/MPI_Type_hvector.3.rst
diff --git a/docs/man-openmpi/man3/MPI_Type_struct.3.rst b/docs/man-openmpi/man3/MPI_Type_struct.3.rst
