mpi.h.in: update several comments

Add some clarifying comments and update some stale comments.

No code or logic changes.

Signed-off-by: Jeff Squyres <jsquyres@cisco.com>

Author: jsquyres

ompi/include/mpi.h.in

@@ -9,7 +9,7 @@
  *                         University of Stuttgart.  All rights reserved.
  * Copyright (c) 2004-2005 The Regents of the University of California.
  *                         All rights reserved.
- * Copyright (c) 2007-2021 Cisco Systems, Inc.  All rights reserved
+ * Copyright (c) 2007-2022 Cisco Systems, Inc.  All rights reserved
  * Copyright (c) 2008-2009 Sun Microsystems, Inc.  All rights reserved.
  * Copyright (c) 2009-2012 Oak Rigde National Laboratory.  All rights reserved.
  * Copyright (c) 2011-2020 Sandia National Laboratories. All rights reserved.
@@ -532,6 +532,11 @@ typedef MPI_Win_errhandler_function MPI_Win_errhandler_fn
 
 /*
  * Miscellaneous constants
+ *
+ * NOTE: Many of the integer constants below *also* appear in
+ * ompi/include/mpif-values.pl.  If you change any of these integer
+ * values below, make sure to also change the corresponding values in
+ * mpif-values.pl, too.
  */
 #define MPI_ANY_SOURCE         -1                      /* match any source rank */
 #define MPI_PROC_NULL          -2                      /* rank of null process */
@@ -572,6 +577,10 @@ typedef MPI_Win_errhandler_function MPI_Win_errhandler_fn
 
 /*
  * Constants for C code to access elements in Fortran MPI status array.
+ *
+ * NOTE: The MPI_F_SOURCE, MPI_F_TAG, MPI_F_ERROR are intentionally 1
+ * smaller than their Fortran equivalents in mpif-values.pl (because C
+ * is 0-indexed and Fortran is 1-indexed).
  */
 #define MPI_F_STATUS_SIZE OMPI_FORTRAN_STATUS_SIZE    /* Size of Fortran MPI status array */
 #define MPI_F_SOURCE      0                           /* Index for MPI_SOURCE */       
@@ -626,7 +635,7 @@ typedef MPI_Win_errhandler_function MPI_Win_errhandler_fn
  * Predefined attribute keyvals
  *
  * DO NOT CHANGE THE ORDER WITHOUT ALSO CHANGING THE ORDER IN
- * src/attribute/attribute_predefined.c and mpif.h.in.
+ * ompi/attribute/attribute_predefined.c and mpif.h.in.
  */
 enum {
     /* MPI-1 */
@@ -744,7 +753,8 @@ enum {
 /*
  * Comparison results.  Don't change the order of these, the group
  * comparison functions rely on it.
- * Do not change the order of these without also modifying mpif.h.in.
+ * Do not change the order of these without also modifying
+ * mpif-values.pl.
  */
 enum {
   MPI_IDENT,
@@ -755,7 +765,8 @@ enum {
 
 /*
  * MPI_Init_thread constants
- * Do not change the order of these without also modifying mpif.h.in.
+ * Do not change the order of these without also modifying
+ * mpif-values.pl.
  */
 enum {
   MPI_THREAD_SINGLE,
@@ -766,8 +777,8 @@ enum {
 
 /*
  * Datatype combiners.
- * Do not change the order of these without also modifying mpif.h.in.
- * (see also mpif-common.h.fin).
+ * Do not change the order of these without also modifying
+ * mpif-values.pl.
  */
 enum {
   MPI_COMBINER_NAMED,
@@ -818,8 +829,8 @@ enum {
 
 /*
  * Communicator split type constants.
- * Do not change the order of these without also modifying mpif.h.in
- * (see also mpif-common.h.fin).
+ * Do not change the order of these without also modifying
+ * mpif-values.pl.
  */
 enum {
   MPI_COMM_TYPE_SHARED,