Added get_bmi_version to sidl and documentation (#111)

* Added get_bmi_version to sidl and documentation * List authors by alpha * Match section headers in SIDL to docs * Move get_bmi_version function to a new metadata section * Reference new metadata functions section * Indicate development status in version Trying to follow semantic versioning (https://semver.org/#spec-item-9). Co-authored-by: Mark Piper <[email protected]>
csdms · Oct 10, 2022 · 61c028f · 61c028f
1 parent b7471a7
commit 61c028f
Show file tree

Hide file tree

Showing 4 changed files with 40 additions and 3 deletions.
diff --git a/AUTHORS.rst b/AUTHORS.rst
@@ -14,6 +14,7 @@ Contributors
 * Richard Barnes
 * Michael Galloy
 * Julian Hofer
+* Rolf Hut
 * Eric Hutton
 * Allen Lee
 * Eric Morway

diff --git a/bmi.sidl b/bmi.sidl
@@ -1,16 +1,19 @@
 //
 // The Basic Model Interface (BMI)
 //
-package csdms version 2.0 {
+package csdms version 2.1-dev.0 {
   interface bmi {
 
-    // Initialize, run, finalize (IRF)
+    // Model and BMI metadata
+    int get_bmi_version(out string version);    
+
+    // Model control: initialize, run, finalize (IRF)
     int initialize(in string config_file);
     int update();
     int update_until(in double time);
     int finalize();
 
-    // Exchange items
+    // Model information
     int get_component_name(out string name);
     int get_input_item_count(out int count);
     int get_output_item_count(out int count);

diff --git a/docs/source/bmi.metadata_funcs.rst b/docs/source/bmi.metadata_funcs.rst
@@ -0,0 +1,30 @@
+.. _metadata_funcs:
+
+Model and BMI metadata functions
+--------------------------------
+
+These functions supply metadata about a model and its BMI.
+
+.. _get_bmi_version:
+
+*get_bmi_version*
+.................
+
+.. code-block:: java
+
+  /* SIDL */
+  int get_bmi_version(out string version);
+
+.. versionadded:: 2.1
+
+This function supplies the version of BMI implemented as a string.
+
+**Implementation notes**
+
+* The version must be >=2.1.
+* In C and Fortran, the *version* argument is a a character array, and an integer
+  status code indicating success (zero) or failure (nonzero) is returned.
+* In C++, Java, and Python, this argument is omitted, and a string -- a basic type
+  in these languages -- is returned from the function.
+
+[:ref:`metadata_funcs` | :ref:`basic_model_interface`]
diff --git a/docs/source/bmi.spec.rst b/docs/source/bmi.spec.rst
@@ -72,6 +72,7 @@ The Basic Model Interface
 The functions that comprise the Basic Model Interface
 can be grouped into categories:
 
+* :ref:`metadata_funcs`
 * :ref:`control_funcs`
 * :ref:`info_funcs`
 * :ref:`var_funcs`
@@ -92,6 +93,7 @@ grouped by functional category.
    ==============================  =========================================
    Function                        Description 
    ==============================  =========================================
+   :ref:`get_bmi_version`          Version of the BMI implemented.
    :ref:`initialize`               Perform startup tasks for the model.
    :ref:`update`                   Advance model state by one time step.
    :ref:`update_until`             Advance model state until the given time.
@@ -135,6 +137,7 @@ grouped by functional category.
    :ref:`get_grid_nodes_per_face`  Get the number of nodes for each face.
    ==============================  =========================================
 
+.. include:: bmi.metadata_funcs.rst
 .. include:: bmi.control_funcs.rst
 .. include:: bmi.info_funcs.rst
 .. include:: bmi.var_funcs.rst