Update documentation based on #58

This commit contains minor text updates; it doesn't include the
reorg or updates to the CMF page suggested in #58; since those are
bigger, I'll handle them separately.

docs/source/bmi.getter_setter.rst

@@ -27,8 +27,8 @@ state variable can be changed or check the new data for validity.
    int get_value(in string name, in array<> dest);
 
 The `get_value` function takes a variable name and copies values into a
-provided buffer.
-The type and size of the buffer depend on the variable,
+provided array parameter.
+The type and size of the array parameter depend on the variable,
 and can be determined through
 :ref:`get_var_type`, :ref:`get_var_nbytes`, etc.
 Recall that arrays are always flattened in BMI,
@@ -39,7 +39,7 @@ even if the model uses dimensional variables.
 * The *dest* argument must be defined and allocated before calling
   `get_value`. Whatever values it contains are overwritten in the call
   to `get_value`.
-* In Python, the buffer is a :term:`numpy` array.
+* In Python, the array parameter is a :term:`numpy` array.
 * In C++, `get_value` is a void function.
 * Depending on how a model is written, a variable may not be
   accessible until after the call to :ref:`initialize`. Likewise, the
@@ -59,7 +59,7 @@ even if the model uses dimensional variables.
 
 The `get_value_ptr` function takes a variable name and returns a reference
 to a variable.
-Unlike the buffer returned from :ref:`get_value`,
+Unlike the array parameter returned from :ref:`get_value`,
 the reference always points to the current values of the variable,
 even if the model's state has changed.
 

docs/source/bmi.grid_funcs.rst

@@ -49,7 +49,6 @@ is given in the :ref:`model_grids` section.
 
 **Implementation notes**
 
-* This function is needed for every :ref:`grid type <model_grids>`.
 * In C++ and Python, the *type* argument is omitted and the grid
   type name is returned from the function.
 
@@ -66,7 +65,8 @@ is given in the :ref:`model_grids` section.
    /* SIDL */
    int get_grid_rank(in int grid, out int rank);
 
-Given a :term:`grid identifier`, get the :term:`rank` of that grid as an integer.
+Given a :term:`grid identifier`, get the :term:`rank` (the number of
+dimensions) of that grid as an integer.
 
 A grid's rank determines the length of the return value
 of many of the following grid functions.

docs/source/bmi.implementation.rst

@@ -34,6 +34,11 @@ here are some tips to help when writing a BMI for a model.
   responsibility to ensure that array information is
   flattened/redimensionalized in the correct order.
 
+* Recall that models can have mulitple grids. This can be particularly
+  useful for defining :term:`exchange items <exchange item>` that
+  don't vary over the model domain; e.g., a diffusivity -- just define
+  the variable on a separate :ref:`scalar grid <unstructured_grids>`.
+
 * Avoid using global variables, if possible. This isn't strictly a BMI
   requirement, but if a model only uses local variables, its BMI will
   be self-contained. This may allow multiple instances of the model to

docs/source/bmi.info_funcs.rst

@@ -43,6 +43,7 @@ but it should be unique to prevent conflicts with other components.
 
 The number of variables the model can use from other models
 implementing a BMI.
+Also the number of variables that can be set with :ref:`set_value`.
 
 **Implementation notes**
 
@@ -64,6 +65,7 @@ implementing a BMI.
 
 The number of variables the model can provide other models
 implementing a BMI.
+Also the number of variables that can be retrieved with :ref:`get_value`.
 
 **Implementation notes**
 
@@ -101,7 +103,7 @@ Standard Names do not have to be used within the model.
   function in a vector, a standard container in the language.
 * In Python, the argument is omitted and the names are returned from the
   function in a tuple, a standard container in the language.
-* A model may have no input variables.
+* A model might have no input variables.
 
 [:ref:`info_funcs` | :ref:`basic_model_interface`]
 

docs/source/bmi.time_funcs.rst

@@ -61,8 +61,9 @@ The end time of the  model.
 
 **Implementation notes**
 
-* If the model doesn't define an end time, a large number (e.g.,
-  1.0e6) is typically chosen.
+* If the model doesn't define an end time, a large number (e.g., the
+  largest floating point number supported on a platform) is typically
+  chosen.
 * In C++ and Python, the argument is omitted and the time is returned
   from the function.
 
@@ -87,7 +88,8 @@ It's recommended to use `time unit conventions`_ from Unidata's
 **Implementation notes**
 
 * Avoid using `years` as a unit, if possible, since a year is
-  difficult to define precisely.
+  difficult to define precisely. UDUNITS defines a year as 365.2422
+  days or 31556926 seconds.
 * In C++ and Python, the argument is omitted and the units are returned
   from the function.
 

docs/source/bmi.var_funcs.rst

@@ -160,6 +160,9 @@ 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.
+* If the given variable is a scalar (i.e., defined on a :ref:`scalar
+  grid <unstructured_grids>`), the return from this function is
+  ignored.
 
 [:ref:`var_funcs` | :ref:`basic_model_interface`]
 

docs/source/model_grids.rst

@@ -33,10 +33,10 @@ its length would be listed first.
 
 .. note::
 
-  The grid shape is the number of :term:`nodes <node>` in the
-  coordinate directions, not the number of cells or
-  elements. It is possible for grid values to be
-  associated with the nodes or with the cells.
+  The grid shape is the number of rows and columns of :term:`nodes
+  <node>`, as opposed to other types of element (such as cells or
+  faces). It is possible for grid values to be associated with the
+  nodes or with the cells.
 
 
 .. _uniform_rectilinear: