Clarify return values (#85)

* Clarify status code values for C and Fortran

* Add comment on using return codes

Author: mdpiper

docs/source/bmi.best_practices.rst

@@ -80,6 +80,8 @@ here are some tips to help when writing a BMI for a model.
   they wrap a very simple model, they give useful insights into how a
   BMI can be implemented in each language.
 
+* Return codes (C and Fortran) and exceptions (C++ and Python) can help with
+  debugging a BMI, and can provide useful information to a user.
 
 .. Links:
 

docs/source/bmi.control_funcs.rst

@@ -39,7 +39,7 @@ formatted.
 * In C and Fortran, the *config_file* argument is passed as
   a character array, whereas in C++ and Python, it's passed as
   a string -- a basic type in these languages.
-* In C and Fortran, an integer status code indicating success or failure
+* In C and Fortran, an integer status code indicating success (zero) or failure (nonzero)
   is returned. In C++ and Python, an exception is raised on failure.
 
 [:ref:`control_funcs` | :ref:`basic_model_interface`]
@@ -68,7 +68,7 @@ function can just return without doing anything.
 
 **Implementation notes**
 
-* In C and Fortran, an integer status code indicating success or failure
+* In C and Fortran, an integer status code indicating success (zero) or failure (nonzero)
   is returned. In C++ and Python, an exception is raised on failure.
 
 [:ref:`control_funcs` | :ref:`basic_model_interface`]
@@ -96,7 +96,7 @@ to reflect that the model was updated to the requested time.
 **Implementation notes**
 
 * Time is always a double-precision value.
-* In C and Fortran, an integer status code indicating success or failure
+* In C and Fortran, an integer status code indicating success (zero) or failure (nonzero)
   is returned. In C++ and Python, an exception is raised on failure.
 
 [:ref:`control_funcs` | :ref:`basic_model_interface`]
@@ -119,7 +119,7 @@ deallocating memory, closing files and printing reports.
 
 **Implementation notes**
 
-* In C and Fortran, an integer status code indicating success or failure
+* In C and Fortran, an integer status code indicating success (zero) or failure (nonzero)
   is returned. In C++ and Python, an exception is raised on failure.
 
 [:ref:`control_funcs` | :ref:`basic_model_interface`]

docs/source/bmi.getter_setter.rst

@@ -44,6 +44,8 @@ even if the model uses dimensional variables.
 * Depending on how a model is written, a variable may not be
   accessible until after the call to :ref:`initialize`. Likewise, the
   variable may not be accessible after calling :ref:`finalize`.
+* In C and Fortran, an integer status code indicating success (zero) or failure
+  (nonzero) is returned.
 
 [:ref:`getter_setter_funcs` | :ref:`basic_model_interface`]
 
@@ -69,6 +71,8 @@ even if the model's state has changed.
 * In C++, the *dest_ptr* argument is omitted, and the reference is
   returned through the function.
 * In Python, a :term:`numpy` array is returned.
+* In C and Fortran, an integer status code indicating success (zero) or failure
+  (nonzero) is returned.
 
 [:ref:`getter_setter_funcs` | :ref:`basic_model_interface`]
 
@@ -126,6 +130,8 @@ even if the model uses dimensional variables.
 * Depending on how a model is written, a variable may not be
   accessible until after the call to :ref:`initialize`. Likewise, the
   variable may not be accessible after calling :ref:`finalize`.
+* In C and Fortran, an integer status code indicating success (zero) or failure
+  (nonzero) is returned.
 
 [:ref:`getter_setter_funcs` | :ref:`basic_model_interface`]
 

docs/source/bmi.grid_funcs.rst

@@ -51,6 +51,8 @@ is given in the :ref:`model_grids` section.
 
 * In C++ and Python, the *type* argument is omitted and the grid
   type name is returned from the function.
+* In C and Fortran, an integer status code indicating success (zero) or failure
+  (nonzero) is returned.
 
 [:ref:`grid_funcs` | :ref:`basic_model_interface`]
 
@@ -79,6 +81,8 @@ of :ref:`get_grid_x`, :ref:`get_grid_y`, etc. are implemented.
 * This function is needed for every :ref:`grid type <model_grids>`.
 * In C++ and Python, the *rank* argument is omitted and the grid
   rank is returned from the function.
+* In C and Fortran, an integer status code indicating success (zero) or failure
+  (nonzero) is returned.
 
 [:ref:`grid_funcs` | :ref:`basic_model_interface`]
 
@@ -107,6 +111,8 @@ for :ref:`unstructured <unstructured_grids>` and
 * This function is needed for every :ref:`grid type <model_grids>`.
 * In C++ and Python, the *size* argument is omitted and the grid
   size is returned from the function.
+* In C and Fortran, an integer status code indicating success (zero) or failure
+  (nonzero) is returned.
 
 [:ref:`grid_funcs` | :ref:`basic_model_interface`]
 
@@ -145,6 +151,8 @@ the cells.
   <structured_grids>`.
 * In Python, the *shape* argument is a :term:`numpy <NumPy>` array.
 * In C++, this is a void function.
+* In C and Fortran, an integer status code indicating success (zero) or failure
+  (nonzero) is returned.
 
 [:ref:`grid_funcs` | :ref:`basic_model_interface`]
 
@@ -174,6 +182,8 @@ the spacing between rows is followed by spacing between columns, ``[dy, dx]``.
   <uniform_rectilinear>` grids.
 * In Python, the *spacing* argument is a :term:`numpy <NumPy>` array.
 * In C++, this is a void function.
+* In C and Fortran, an integer status code indicating success (zero) or failure
+  (nonzero) is returned.
 
 [:ref:`grid_funcs` | :ref:`basic_model_interface`]
 
@@ -204,6 +214,8 @@ the origin is given in the column dimension, followed by the row dimension,
   <uniform_rectilinear>` grids.
 * In Python, the *origin* argument is a :term:`numpy <NumPy>` array.
 * In C++, this is a void function.
+* In C and Fortran, an integer status code indicating success (zero) or failure
+  (nonzero) is returned.
 
 [:ref:`grid_funcs` | :ref:`basic_model_interface`]
 
@@ -232,6 +244,8 @@ See :ref:`model_grids` for more information.
   and all :ref:`unstructured <unstructured_grids>` grids.
 * In Python, the *x* argument is a :term:`numpy <NumPy>` array.
 * In C++, this is a void function.
+* In C and Fortran, an integer status code indicating success (zero) or failure
+  (nonzero) is returned.
 
 [:ref:`grid_funcs` | :ref:`basic_model_interface`]
 
@@ -260,6 +274,8 @@ See :ref:`model_grids` for more information.
   and all :ref:`unstructured <unstructured_grids>` grids.
 * In Python, the *y* argument is a :term:`numpy <NumPy>` array.
 * In C++, this is a void function.
+* In C and Fortran, an integer status code indicating success (zero) or failure
+  (nonzero) is returned.
 
 [:ref:`grid_funcs` | :ref:`basic_model_interface`]
 
@@ -288,6 +304,8 @@ See :ref:`model_grids` for more information.
   and all :ref:`unstructured <unstructured_grids>` grids.
 * In Python, the *z* argument is a :term:`numpy <NumPy>` array.
 * In C++, this is a void function.
+* In C and Fortran, an integer status code indicating success (zero) or failure
+  (nonzero) is returned.
 
 [:ref:`grid_funcs` | :ref:`basic_model_interface`]
 
@@ -310,6 +328,8 @@ Get the number of :term:`nodes <node>` in the grid.
   <unstructured_grids>` grids.
 * In C++ and Python, the *count* argument is omitted and the node
   count is returned from the function.
+* In C and Fortran, an integer status code indicating success (zero) or failure
+  (nonzero) is returned.
 
 [:ref:`grid_funcs` | :ref:`basic_model_interface`]
 
@@ -332,6 +352,8 @@ Get the number of :term:`edges <edge>` in the grid.
   <unstructured_grids>` grids.
 * In C++ and Python, the *count* argument is omitted and the edge
   count is returned from the function.
+* In C and Fortran, an integer status code indicating success (zero) or failure
+  (nonzero) is returned.
 
 [:ref:`grid_funcs` | :ref:`basic_model_interface`]
 
@@ -354,6 +376,8 @@ Get the number of :term:`faces <face>` in the grid.
   <unstructured_grids>` grids.
 * In C++ and Python, the *count* argument is omitted and the face
   count is returned from the function.
+* In C and Fortran, an integer status code indicating success (zero) or failure
+  (nonzero) is returned.
 
 [:ref:`grid_funcs` | :ref:`basic_model_interface`]
 
@@ -380,6 +404,8 @@ node at edge head. The total length of the array is
   <unstructured_grids>` grids.
 * In Python, the *edge_nodes* argument is a :term:`numpy <NumPy>` array.
 * In C++, this is a void function.
+* In C and Fortran, an integer status code indicating success (zero) or failure
+  (nonzero) is returned.
 
 [:ref:`grid_funcs` | :ref:`basic_model_interface`]
 
@@ -405,6 +431,8 @@ The length of the array returned is the sum of the values of
   <unstructured_grids>` grids.
 * In Python, the *face_edges* argument is a :term:`numpy <NumPy>` array.
 * In C++, this is a void function.
+* In C and Fortran, an integer status code indicating success (zero) or failure
+  (nonzero) is returned.
 
 [:ref:`grid_funcs` | :ref:`basic_model_interface`]
 
@@ -435,6 +463,8 @@ the length of the array is the sum of the values of
   <unstructured_grids>` grids.
 * In Python, the *face_nodes* argument is a :term:`numpy <NumPy>` array.
 * In C++, this is a void function.
+* In C and Fortran, an integer status code indicating success (zero) or failure
+  (nonzero) is returned.
 
 [:ref:`grid_funcs` | :ref:`basic_model_interface`]
 
@@ -460,5 +490,7 @@ The number of edges per face is equal to the number of nodes per face.
   <unstructured_grids>` grids.
 * In Python, the *nodes_per_face* argument is a :term:`numpy <NumPy>` array.
 * In C++, this is a void function.
+* In C and Fortran, an integer status code indicating success (zero) or failure
+  (nonzero) is returned.
 
 [:ref:`grid_funcs` | :ref:`basic_model_interface`]

docs/source/bmi.info_funcs.rst

@@ -24,8 +24,9 @@ but it should be unique to prevent conflicts with other components.
 
 **Implementation notes**
 
-* In C and Fortran, the *name* argument is a a character array.
-  In C++ and Python, this argument is omitted, and a string -- a basic type
+* In C and Fortran, the *name* argument is a a character array, and an integer
+  status code indicating success (zero) or failure (nonzero) is returned.
+* In C++ and Python, this argument is omitted, and a string -- a basic type
   in these languages -- is returned from the function.
 
 [:ref:`info_funcs` | :ref:`basic_model_interface`]
@@ -49,6 +50,8 @@ Also the number of variables that can be set with :ref:`set_value`.
 
 * In C++ and Python, the argument is omitted and the count is returned
   from the function.
+* In C and Fortran, an integer status code indicating success (zero) or failure
+  (nonzero) is returned.
 
 [:ref:`info_funcs` | :ref:`basic_model_interface`]
 
@@ -69,8 +72,10 @@ Also the number of variables that can be retrieved with :ref:`get_value`.
 
 **Implementation notes**
 
-* In C++ and Python, the argument is omittedq and the count is
+* In C++ and Python, the argument is omitted and the count is
   returned from the function.
+* In C and Fortran, an integer status code indicating success (zero) or failure
+  (nonzero) is returned.
 
 [:ref:`info_funcs` | :ref:`basic_model_interface`]
 
@@ -98,7 +103,8 @@ Standard Names do not have to be used within the model.
 **Implementation notes**
 
 * In C and Fortran, the names are passed back as an array of character
-  pointers (because the variable names could have differing lengths).
+  pointers (because the variable names could have differing lengths), and an
+  integer status code indicating success (zero) or failure (nonzero) is returned.
 * In C++, the argument is omitted and the names are returned from the
   function in a vector, a standard container in the language.
 * In Python, the argument is omitted and the names are returned from the
@@ -131,7 +137,8 @@ Standard Names do not have to be used within the model.
 **Implementation notes**
 
 * In C and Fortran, the names are passed back as an array of character
-  pointers (because the variable names could have differing lengths).
+  pointers (because the variable names could have differing lengths), and an
+  integer status code indicating success (zero) or failure (nonzero) is returned.
 * In C++, the argument is omitted and the names are returned from the
   function in a vector, a standard container in the language.
 * In Python, the argument is omitted and the names are returned from the

docs/source/bmi.time_funcs.rst

@@ -22,6 +22,8 @@ The current model time.
 
 * In C++ and Python, the argument is omitted and the time is returned
   from the function.
+* In C and Fortran, an integer status code indicating success (zero) or failure
+  (nonzero) is returned.
 
 [:ref:`time_funcs` | :ref:`basic_model_interface`]
 
@@ -43,6 +45,8 @@ The start time of the  model.
 * The start time in BMI is typically defined to be 0.0.
 * In C++ and Python, the argument is omitted and the time is returned
   from the function.
+* In C and Fortran, an integer status code indicating success (zero) or failure
+  (nonzero) is returned.
 
 [:ref:`time_funcs` | :ref:`basic_model_interface`]
 
@@ -66,6 +70,8 @@ The end time of the  model.
   chosen.
 * In C++ and Python, the argument is omitted and the time is returned
   from the function.
+* In C and Fortran, an integer status code indicating success (zero) or failure
+  (nonzero) is returned.
 
 [:ref:`time_funcs` | :ref:`basic_model_interface`]
 
@@ -95,6 +101,8 @@ It's recommended to use `time unit conventions`_ from Unidata's
   use ``"none"``.
 * In C++ and Python, the argument is omitted and the units are returned
   from the function.
+* In C and Fortran, an integer status code indicating success (zero) or failure
+  (nonzero) is returned.
 
 [:ref:`time_funcs` | :ref:`basic_model_interface`]
 
@@ -119,5 +127,7 @@ The time step is always expressed as a floating point value.
   backward).
 * In C++ and Python, the argument is omitted and the time step is returned
   from the function.
+* In C and Fortran, an integer status code indicating success (zero) or failure
+  (nonzero) is returned.
 
 [:ref:`time_funcs` | :ref:`basic_model_interface`]

docs/source/bmi.var_funcs.rst

@@ -36,6 +36,8 @@ A model can have one or more grids.
 * Grid identifiers start at 0.
 * In C++ and Python, the *grid* argument is omitted and the grid
   identifier is returned from the function.
+* In C and Fortran, an integer status code indicating success (zero) or
+  failure (nonzero) is returned.
 
 [:ref:`var_funcs` | :ref:`basic_model_interface`]
 
@@ -61,6 +63,8 @@ while in Fortran, use `integer`, `real`, and `double precision`.
 
 * In C++ and Python, the *type* argument is omitted and the variable
   type name is returned from the function.
+* In C and Fortran, an integer status code indicating success (zero) or failure
+  (nonzero) is returned.
 
 [:ref:`var_funcs` | :ref:`basic_model_interface`]
 
@@ -94,6 +98,8 @@ full description of valid unit names and a list of supported units.
 * Variables without units should use ``"none"``.
 * In C++ and Python, the *units* argument is omitted and the variable
   units name is returned from the function.
+* In C and Fortran, an integer status code indicating success (zero) or failure
+  (nonzero) is returned.
 
 [:ref:`var_funcs` | :ref:`basic_model_interface`]
 
@@ -117,6 +123,8 @@ For example, if data for a variable are stored as 64-bit integers,
 
 * In C++ and Python, the *size* argument is omitted and the item size
   is returned from the function.
+* In C and Fortran, an integer status code indicating success (zero) or failure
+  (nonzero) is returned.
 
 [:ref:`var_funcs` | :ref:`basic_model_interface`]
 
@@ -138,6 +146,8 @@ a variable; i.e., the number of items multiplied by the size of each item.
 
 * In C++ and Python, the *nbytes* argument is omitted and the total
   amount of memory used by the variable is returned from the function.
+* In C and Fortran, an integer status code indicating success (zero) or failure
+  (nonzero) is returned.
 
 [:ref:`var_funcs` | :ref:`basic_model_interface`]
 
@@ -164,9 +174,10 @@ element the variable is defined. Valid return values are:
 
 * In C++ and Python, the *location* argument is omitted and the location
   is returned from the function.
+* In C and Fortran, an integer status code indicating success (zero) or failure
+  (nonzero) is returned.
 * If the given variable is a scalar (i.e., defined on a :ref:`scalar
-  grid <unstructured_grids>`), the return from this function is
-  ignored.
+  grid <unstructured_grids>`), the location from this function is ignored.
 
 [:ref:`var_funcs` | :ref:`basic_model_interface`]