Finished API Compatibility Macros.

3 files changed, 102 insertions, 23 deletions

diff --git a/doxygen/dox/H5Oget_info_by_name.dox b/doxygen/dox/H5Oget_info_by_name.dox
index 3276c5a..b1b9540 100644
--- a/doxygen/dox/H5Oget_info_by_name.dox
+++ b/doxygen/dox/H5Oget_info_by_name.dox
@@ -12,9 +12,9 @@
  *          document closely.
  *
  *          In HDF5 versions 1.12 and after, #H5Oget_info_by_name is mapped to
- *          \ref H5Oget_info_by_name3().  In version 1.10 #H5Oget_info_by_name is 
- *          identical to \ref H5Oget_info_by_name1(). 
- * 
+ *          \ref H5Oget_info_by_name3().  In version 1.10 #H5Oget_info_by_name is
+ *          identical to \ref H5Oget_info_by_name1().
+ *
  *          Specific compile-time compatibility flags and the resulting
  *          mappings are as follows:
  *
@@ -66,27 +66,27 @@
  *  </tr>
  *  <tr>
  *      <td></td>
- *      <td>This change was added to restore the broken API compatibility 
+ *      <td>This change was added to restore the broken API compatibility
  *          introduced in HDF5-1.10.3.</td>
  *  </tr>
  *  <tr>
  *      <td>1.10.3</td>
- *      <td>The function \ref H5Oget_info_by_name() was renamed 
+ *      <td>The function \ref H5Oget_info_by_name() was renamed
  *          to \ref H5Oget_info_by_name1.</td>
  *  </tr>
  *  <tr>
  *      <td></td>
- *      <td>The macro #H5Oget_info_by_name was renamed to 
+ *      <td>The macro #H5Oget_info_by_name was renamed to
  *          \ref H5Oget_info_by_name1().</td>
  *  </tr>
  *  <tr>
  *      <td></td>
- *      <td>The macro #H5Oget_info_by_name and the function \ref H5Oget_info_name2() 
+ *      <td>The macro #H5Oget_info_by_name and the function \ref H5Oget_info_by_name2()
  *          were introduced in this release.</td>
  *  </tr>
  *  <tr>
  *      <td>1.8.8</td>
- *      <td>Fortran 2003 subroutine and \ref h5o_info_t derived 
+ *      <td>Fortran 2003 subroutine and \ref H5O_info_t derived
  *          type introduced in this release.</td>
  *  </tr>
  *  <tr>
@@ -95,5 +95,5 @@
  *  </tr>
  * </table>
  *
- * 
+ *
  */
diff --git a/doxygen/dox/api-compat-macros.dox b/doxygen/dox/api-compat-macros.dox
index c5c868b..6b85ccb 100644
--- a/doxygen/dox/api-compat-macros.dox
+++ b/doxygen/dox/api-compat-macros.dox
@@ -146,8 +146,8 @@
   <table border="1" cellpadding="3">
   <tr>
   <th>\Code{configure} flag</th>
-  <th>Macros map to release<br/>(versioned function; \Code{H5Lvisit} shown)</th>
-  <th>Deprecated functions available? <br/>(\Code{H5Lvisit1})</th>
+  <th>Macros map to release <br/> (versioned function; \Code{H5Lvisit} shown)</th>
+  <th>Deprecated functions available? <br/> (\Code{H5Lvisit1})</th>
   </tr>
   <tr align="center">
   <td>\Code{--with-default-api-version=v112} <br/> (the default in 1.12)</td>
@@ -304,7 +304,7 @@
   \subsubsection fun-options-112 Function Mapping Options in Releases 1.12.x
   <table>
   <tr>
-  <th style="text-align: left;">Macro<br/>(\Code{H5xxx})</th>
+  <th style="text-align: left;">Macro <br/> (\Code{H5xxx})</th>
   <th>Default function used if no macro specified
   <ul><li>Function/struct mapping:\Code{H5xxx_vers=N}</li></ul>
   </th>
@@ -507,7 +507,7 @@
   <table>
   <tr>
   <th>Macro</th>
-  <th>Default function used<br/><sub>(if no macro specified)</sub></th>
+  <th>Default function used <br/> <sub>(if no macro specified)</sub></th>
   <th>Introduced in</th>
   <th>\Code{h5cc} version flag and value</th>
   <th>Mapped to function or struct</th>
@@ -603,7 +603,7 @@
   <tr>
   <th>Macro</th>
   <th><code>h5cc</code> version flag and value</th>
-  <th>Mapped to function<br/>or struct</th>
+  <th>Mapped to function <br/> or struct</th>
   </tr>
   <tr>
   <td rowspan="2">H5Acreate()</td>
@@ -686,7 +686,7 @@
   <td>H5Eget_auto2()</td>
   </tr>
   <tr>
-  <td rowspan="2">\ref H5E_auto_t <br/> Struct for H5Eset_auto() <br/> and H5Eget_auto()</td>
+  <td rowspan="2">\ref H5E_auto_t <br/> struct for H5Eset_auto() <br/> and H5Eget_auto()</td>
   <td>\Code{DH5E_auto_t_vers=1}</td>
   <td>\ref H5E_auto1_t</td>
   </tr>
@@ -719,12 +719,12 @@
   </tr>
   <tr>
   <td>\Code{DH5Gopen_vers=2}</td>
-  <td>H5Gopen2}</td>
+  <td>H5Gopen2()</td>
   </tr>
   <tr>
   <td rowspan="2">H5Pget_filter()</td>
   <td>\Code{DH5Pget_filter_vers=1}</td>
-  <td>H5Pget_filter1}()/td>
+  <td>H5Pget_filter1()</td>
   </tr>
   <tr>
   <td>\Code{DH5Pget_filter_vers=2}</td>
@@ -751,7 +751,7 @@
   <tr>
   <td rowspan="2">H5Pregister()</td>
   <td>\Code{DH5Pregister_vers=1}</td>
-  <td>H5Pregister1}</td>
+  <td>H5Pregister1()</td>
   </tr>
   <tr>
   <td>\Code{DH5Pregister_vers=2}</td>
@@ -803,7 +803,7 @@
   <td>H5Topen2()</td>
   </tr>
   <tr>
-  <td rowspan="2">\ref H5Z_class_t Struct for H5Zregister()</td>
+  <td rowspan="2">\ref H5Z_class_t struct for H5Zregister()</td>
   <td>\Code{DH5Z_class_t_vers=1}</td>
   <td>\ref H5Z_class1_t</td>
   </tr>
@@ -811,10 +811,89 @@
   <td>\Code{DH5Z_class_t_vers=2}</td>
   <td>\ref H5Z_class2_t</td>
   </tr>
-  </table></div>
-
+  </table>
+  </div>
 
   \subsubsection further Further Information
+  It is possible to specify multiple function mappings for a single application build:
+  \code{.sh}
+  h5cc ... -DH5Rdereference_vers=1 -DH5Fget_info_vers=2 ...
+  \endcode
+  As a result of the function and struct mappings in this compile example, all
+  occurrences of the macro \Code{H5Rdereference} will be mapped to \Code{H5Rdereference1}
+  and all occurrences of the macro \Code{H5Fget_info} will be mapped to \Code{H5Fget_info2}
+  for the application being built.
+
+  The function and struct mappings can be used to guarantee that a given API compatibility
+  macro will be mapped to the desired underlying function or struct version regardless of
+  the library or application mappings. In cases where an application may benefit greatly
+  from features offered by some of the later APIs, or must continue to use some earlier
+  API versions for compatibility reasons, this fine-grained control may be very important.
+
+  As noted earlier, the function mappings can only reference versioned functions that are
+  included in the HDF5 library, as determined by the configure flag used to build the
+  library. For example, if the HDF5 library being linked with the application was built
+  with the \Code{--disable-deprecated-symbols} option, version 1 of the underlying functions
+  would not be available, and the example above that defined \Code{H5Rdereference_vers=1}
+  would not be supported.
+
+  The function mappings do not negate any available functions. If \Code{H5Rdereference1}
+  is available in the installed version of the HDF5 library, and the application was not
+  compiled with the \Code{-DH5_NO_DEPRECATED_SYMBOLS} flag, the function \Code{H5Rdereference1}
+  will remain available to the application through its versioned name. Similarly,
+  \Code{H5Rdereference2} will remain available to the application as \Code{H5Rdereference2}.
+  The function mapping version flag \Code{H5Rdereference_vers} only controls the mapping of
+  the API compatibility macro \Code{H5Rdereference} to one of the two available functions.
+
+  This can be especially useful in any case where the programmer does not have direct control
+  over global macro definitions, such as when writing code meant to be copied to multiple
+  applications or when writing code in a header file.
+
   \section macros Compatibility Macros in HDF5 1.6.8 and Later
+  A series of similar compatibility macros were introduced into the release 1.6
+  series of the library, starting with release 1.6.8. These macros simply alias the
+  '1' version functions, callbacks, and typedefs listed above to their original
+  non-numbered names.
+
+  These macros were strictly a forward-looking feature at that time; they were not
+  necessary for compatibility in 1.6.x. These macros were created at that time to
+  enable writing code that could be used with any version of the library after 1.6.8
+  and any library compilation options except \Code{H5_NO_DEPRECATED_SYMBOLS}, by always
+  using the '1' version of versioned functions and types. For example, \Code{H5Dopen1}
+  will always be interpreted in exactly the same manner by any version of the library
+  since 1.6.8.
+
   \section use-case Common Use Case
-*/
\ No newline at end of file
+  A common scenario where the API compatibility macros may be helpful is the migration
+  of an existing application to a new HDF5 release. An incremental migration plan is
+  outlined here:
+  <ol>
+  <li>Build the HDF5 library without specifying any library mapping \Code{configure}
+      flag. In this default mode, the 1.6.x, 1.8.x, and 1.10.x versions of the
+      underlying functions are available, and the API compatibility macros will
+      be mapped to the current HDF5 versioned functions.</li>
+  <li>Compile the application with the \Code{-DH5_USE_NN_API} application mapping
+      option if it was written for use with an earlier HDF5 library. Because the
+      application mapping overrides the library mapping, the macros will all be
+      mapped to the earlier versions of the functions.</li>
+  <li>Remap one API compatibility macro at a time (or sets of macros), to use the
+      current HDF5 versions. At each stage, use the function mappings to map the macros
+      being worked on to the current versions. For example, use the
+      \Code{-DH5Rdereference_vers=2} version flag setting to remap the \Code{H5Rdereference}
+      macro to \Code{H5Rdereference2}, the 1.10.x version.
+
+      During this step, the application code will need to be modified to change the calling
+      parameters used with the API compatibility macros to match the number and type
+      of the 1.10.x versioned functions. The macro name, for example \Code{H5Rdereference},
+      should continue to be used in the code, to allow for possible re-mappings to later
+      versioned functions in a future release.</li>
+   <li>After all macros have been migrated to the latest versioned functions in step 3,
+       compile the application without any application or function mappings. This build
+       uses the library mappings set in step 1, and maps API compatibility macros to the
+       latest versions.</li>
+   <li>Finally, compile the application with the application mapping
+       \Code{-DH5_NO_DEPRECATED_SYMBOLS}, and address any failures to complete
+       the application migration process.</li>
+   </ol>
+
+ */
\ No newline at end of file
diff --git a/doxygen/dox/mainpage.dox b/doxygen/dox/mainpage.dox
index 7b62916..83fc323 100644
--- a/doxygen/dox/mainpage.dox
+++ b/doxygen/dox/mainpage.dox
@@ -33,4 +33,4 @@
  * opportunity to close any temporary data structures that were set up when the
  * routine was called. The C++ application should save some state as the
  * routine is started so that any problem that occurs might be diagnosed.
- */
+ */
\ No newline at end of file