Updates and tweaks to the documentation of the new MCA parameter

system (written in conjunction with Nathan).

This commit was SVN r28758.

opal/mca/base/mca_base_var.h

@@ -112,15 +112,18 @@ typedef enum {
 /**
  * MCA variable scopes
  *
- * Equivalent to MPIT scopes
+ * Equivalent to MPI_T scopes with the same base name (e.g.,
+ * MCA_BASE_VAR_SCOPE_CONSTANT corresponts to MPI_T_SCOPE_CONSTANT).
  */
 typedef enum {
-    /** The value of this variable will not change after it 
+    /** The value of this variable will not change after it is
-        is registered. Implies !MCA_BASE_VAR_FLAG_SETTABLE */
+        registered.  This flag is incompatible with
+        MCA_BASE_VAR_FLAG_SETTABLE, and also implies
+        MCA_BASE_VAR_SCOPE_READONLY. */
     MCA_BASE_VAR_SCOPE_CONSTANT,
-    /** The value of this variable may change but it should not be
+    /** Setting the READONLY flag means that the mca_base_var_set()
-        changed using the mca_base_var_set function. Implies
+        function cannot be used to set the value of this variable
-        !MCA_BASE_VAR_FLAG_SETTABLE */
+        (e.g., the MPI_T_cvar_write() MPI_T function). */
     MCA_BASE_VAR_SCOPE_READONLY,
     /** The value of this variable may be changed locally. */
     MCA_BASE_VAR_SCOPE_LOCAL,
@@ -446,59 +449,67 @@ OPAL_DECLSPEC int mca_base_var_group_get_stamp (void);
  * This function registers an MCA variable and associates it
  * with a specific group.
  *
- * The {description} is a string of arbitrary length (verbose is
+ * {description} is a string of arbitrary length (verbose is good!)
- * good!) for explaining what the variable is for and what its
+ * for explaining what the variable is for and what its valid values
- * valid values are.  This message is used in help messages, such
+ * are.  This message is used in help messages, such as the output
- * as the output from the ompi_info executable.
+ * from the ompi_info executable.  The {description} string is copied
+ * internally; the caller can free {description} upon successful
+ * return.
  *
- * The {enumerator} describes the valid values of an integer
+ * {enumerator} is either NULL or a handle that was created via
- * variable. The variable may be set to either the enumerator value
+ * mca_base_var_enum_create(), and describes the valid values of an
- * (0, 1, 2, etc) or a string representing that value. The
+ * integer variable (i.e., one with type MCA_BASE_VAR_TYPE_INT).  When
- * value provided by the user will be compared against the
+ * a non-NULL {enumerator} is used, the value set for this variable by
- * values in the enumerator. The {enumerator} is not valid with
+ * the user will be compared against the values in the enumerator.
- * any other type of variable. {enumerator} is retained until
+ * The MCA variable system will allow the parameter to be set to
- * either the variable is deregistered using mca_base_var_deregister(),
+ * either one of the enumerator values (0, 1, 2, etc) or a string
- * mca_base_var_group_deregister(), or mca_base_var_finalize().
+ * representing one of those values.  {enumerator} is retained until
+ * either the variable is deregistered using
+ * mca_base_var_deregister(), mca_base_var_group_deregister(), or
+ * mca_base_var_finalize().  {enumerator} should be NULL for
+ * parameters that do not support enumerated values.
  *
- * The {flags} indicate attributes of this variable (internal,
+ * {flags} indicate attributes of this variable (internal, settable,
- * settable, default only, etc).
+ * default only, etc.), as listed below.
  *
- * If MCA_BASE_VAR_FLAG_SETTABLE is set in {flags}, this variable
+ * If MCA_BASE_VAR_FLAG_SETTABLE is set in {flags}, this variable may
- * may be set using mca_base_var_set_value().
+ * be set using mca_base_var_set_value() (i.e., the MPI_T interface).
  *
  * If MCA_BASE_VAR_FLAG_INTERNAL is set in {flags}, this variable
  * is not shown by default in the output of ompi_info.  That is,
  * this variable is considered internal to the Open MPI implementation
  * and is not supposed to be viewed / changed by the user.
  *
- * If MCA_BASE_VAR_FLAG_DEFAULT_ONLY is set in {flags}, then the
+ * If MCA_BASE_VAR_FLAG_DEFAULT_ONLY is set in {flags}, then the value
- * value provided in storage will not be modified by the MCA
+ * provided in storage will not be modified by the MCA variable system
- * variable system. It is up to the caller to specify (using the scope)
+ * (i.e., users cannot set the value of this variable via CLI
- * if this value may change (MCA_BASE_VAR_SCOPE_READONLY)
+ * parameter, environment variable, file, etc.). It is up to the
- * or remain constant (MCA_BASE_VAR_SCOPE_CONSTANT).
+ * caller to specify (using the scope) if this value may change
- * MCA_BASE_VAR_FLAG_DEFAULT_ONLY must not be specified with
+ * (MCA_BASE_VAR_SCOPE_READONLY) or remain constant
- * MCA_BASE_VAR_FLAG_SETTABLE.
+ * (MCA_BASE_VAR_SCOPE_CONSTANT).  MCA_BASE_VAR_FLAG_DEFAULT_ONLY must
+ * not be specified with MCA_BASE_VAR_FLAG_SETTABLE.
  *
  * Set MCA_BASE_VAR_FLAG_DEPRECATED in {flags} to indicate that
  * this variable name is deprecated. The user will get a warning
  * if they set this variable.
  *
- * The {scope} is for informational purposes to indicate how this
+ * {scope} is for informational purposes to indicate how this variable
- * variable should be set or if it is considered constant or readonly.
+ * can be set, or if it is considered constant or readonly (which, by
- * A readonly scope means something different than setting {read_only}
+ * MPI_T's definitions, are different things).  See the comments in
- * to true. A readonly scope will still allow the variable to be
+ * the description of mca_base_var_scope_t for information about the
- * overridden by a file or environment variable.
+ * different scope meanings.
  *
- * The {storage} pointer points to a char *, int, or bool where the
+ * {storage} points to a (char *), (int), or (bool) where the value of
- * value of this variable is stored. The {type} indicates the type
+ * this variable is stored ({type} indicates the type of this
- * of this pointer. The initial value passed to this function may
+ * pointer).  The location pointed to by {storage} must exist until
- * be overwritten if the MCA_BASE_VAR_FLAG_DEFAULT_ONLY flag is not
+ * the variable is deregistered.  Note that the initial value in
- * set and either an environment variable or a file value for this
+ * {storage} may be overwritten if the MCA_BASE_VAR_FLAG_DEFAULT_ONLY
- * variable is set. If {storage} points to a char * the value will
+ * flag is not set (e.g., if the user sets this variable via CLI
- * be duplicated and it is up to the caller to retain and free the
+ * option, environment variable, or file value).  If input value of
- * original value if needed. Any string value set when this
+ * {storage} points to a (char *), the pointed-to string will be
- * variable is deregistered (including finalize) will be freed
+ * duplicated and maintained internally by the MCA variable system;
- * automatically.
+ * the caller may free the original string after this function returns
+ * successfully.  
  */
 OPAL_DECLSPEC int mca_base_var_register (const char *project_name, const char *framework_name,
                                          const char *component_name, const char *variable_name,