Doxygen updates for functions that use printf expansion (#5816)

* Doxygen updates related to printf parsing in family, multi, and split
drivers, and VDS. Update error message.

Author: fortnern

src/H5FDfamily.c

@@ -738,7 +738,9 @@ H5FD__family_open(const char *name, unsigned flags, hid_t fapl_id, haddr_t maxad
             name = temp;
         }
         else
-            HGOTO_ERROR(H5E_VFL, H5E_FILEEXISTS, NULL, "file names not unique");
+            HGOTO_ERROR(H5E_VFL, H5E_FILEEXISTS, NULL,
+                        "differing member numbers do not produce unique member file names - try inserting "
+                        "\"%%06d\" into the file name string");
     }
 
     /* Open all the family members */

src/H5FDfamily.h

@@ -61,6 +61,25 @@ H5_DLLVAR hid_t H5FD_FAMILY_id_g;
  *          \p memb_fapl_id is the identifier of the file access property list
  *          to be used for each family member.
  *
+ *          The family file driver uses \TText{snprintf} to generate the member file
+ *          names, passing the member number as an unsigned int.  The file name
+ *          used with the family file driver must therefore contain a single
+ *          \TText{printf} format specifier that indicates a variable of the correct
+ *          width and produces unique strings for each member number passed as a
+ *          parameter to snprintf. For example one might insert \TText{%06d}
+ *          into the file name string. There must be no other format specifiers
+ *          in the string.
+ *
+ *          If this file driver is for the source file of a virtual dataset
+ *          (VDS) \TText{printf}-style mapping, special care must be taken. In this case
+ *          the VDS code expands the file name with \TText{snprintf} first, then the
+ *          family driver second. This means that, while the format specifier
+ *          for the VDS block number is inserted normally, the format specifier
+ *          for the family file driver member number must be escaped such that
+ *          it is only recognized as a format specifier the second time it is
+ *          run through \TText{snprintf}. As an example one may use \TText{%%06d} as
+ *          the member file number format specifier in the source file name.
+ *
  * \version 1.8.0 Behavior of the \p memb_size parameter was changed.
  * \since 1.4.0
  *

src/H5FDmulti.h

@@ -70,9 +70,9 @@ H5_DLLVAR hid_t H5FD_MULTI_id_g;
  *          usage type that will be associated with a file.
  *
  *          The array \p memb_name should be a name generator (a
- *          \TText{printf}-style format with a \TText{%s} which will be replaced
+ *          \TText{printf}-style format with a \TText{%%s} which will be replaced
  *          with the name passed to H5FDopen(), usually from H5Fcreate() or
- *          H5Fopen()).
+ *          H5Fopen()). There must be no other format specifiers in the string.
  *
  *          The array \p memb_addr specifies the offsets within the virtual
  *          address space, from 0 (zero) to #HADDR_MAX, at which each type of
@@ -102,7 +102,7 @@ H5_DLLVAR hid_t H5FD_MULTI_id_g;
  *          \p memb_name
  *          </td>
  *          <td>
- *          The default string is \TText{%s-X.h5} where \c X is one of the following letters:
+ *          The default string is \TText{%%s-X.h5} where \c X is one of the following letters:
  *          - \c s for #H5FD_MEM_SUPER
  *          - \c b for #H5FD_MEM_BTREE
  *          - \c r for #H5FD_MEM_DRAW
@@ -209,7 +209,7 @@ H5_DLL herr_t H5Pget_fapl_multi(hid_t fapl_id, H5FD_mem_t *memb_map /*out*/, hid
  *          \p meta_ext is the filename extension for the metadata file. The
  *          extension is appended to the name passed to H5FDopen(), usually from
  *          H5Fcreate() or H5Fopen(), to form the name of the metadata file. If
- *          the string \TText{%s} is used in the extension, it works like the
+ *          the string \TText{%%s} is used in the extension, it works like the
  *          name generator as in H5Pset_fapl_multi().
  *
  *          \p meta_plist_id is the file access property list identifier for the
@@ -218,8 +218,9 @@ H5_DLL herr_t H5Pget_fapl_multi(hid_t fapl_id, H5FD_mem_t *memb_map /*out*/, hid
  *          \p raw_ext is the filename extension for the raw data file. The
  *          extension is appended to the name passed to H5FDopen(), usually from
  *          H5Fcreate() or H5Fopen(), to form the name of the raw data file. If
- *          the string \TText{%s} is used in the extension, it works like the
- *          name generator as in H5Pset_fapl_multi().
+ *          the string \TText{%%s} is used in the extension, it works like the
+ *          name generator as in H5Pset_fapl_multi(). There must be no other
+ *          format specifiers in the string.
  *
  *          \p raw_plist_id is the file access property list identifier for the
  *          raw data file.

src/H5Ppublic.h

@@ -7078,7 +7078,7 @@ H5_DLL herr_t H5Pset_szip(hid_t plist_id, unsigned options_mask, unsigned pixels
  * \param[in] vspace_id The dataspace identifier with the selection within the
  *            virtual dataset applied, possibly an unlimited selection
  * \param[in] src_file_name The name of the HDF5 file where the source dataset is
- *            located or a \TText{"."} (period) for a source dataset in the same
+ *            located or a \TText{.} (period) for a source dataset in the same
  *            file. The file might not exist yet. The name can be specified using
  *            a C-style \c printf statement as described below.
  * \param[in] src_dset_name The path to the HDF5 dataset in the file specified by
@@ -7101,14 +7101,14 @@ H5_DLL herr_t H5Pset_szip(hid_t plist_id, unsigned options_mask, unsigned pixels
  *      treated as literals except for the following substitutions:
  *      <table>
  *      <tr>
- *      <td>\TText{"%%"}</td>
- *      <td>Replaced with a single \TText{"%"} (percent) character.</td>
+ *      <td>\TText{%%}</td>
+ *      <td>Replaced with a single \TText{%} (percent) character.</td>
  *      </tr>
  *      <tr>
- *      <td><code>"%<d>b"</code></td>
- *      <td>Where <code>"<d>"</code> is the virtual dataset dimension axis (0-based)
- *          and \TText{"b"} indicates that the block count of the selection in that
- *          dimension should be used. The full expression (for example, \TText{"%0b"})
+ *      <td><code>%\<d\>b</code></td>
+ *      <td>Where <code>\<d\></code> is the virtual dataset dimension axis (0-based)
+ *          and \TText{b} indicates that the block count of the selection in that
+ *          dimension should be used. The full expression (for example, \TText{%0b})
  *          is replaced with a single numeric value when the mapping is evaluated at
  *          VDS access time. Example code for many source and virtual dataset mappings
  *          is available in the "Examples of Source to Virtual Dataset Mapping"
@@ -7121,11 +7121,21 @@ H5_DLL herr_t H5Pset_szip(hid_t plist_id, unsigned options_mask, unsigned pixels
  *      If the printf form is used for the source file or dataset names, the
  *      selection in the source dataset's dataspace must be fixed-size.
  *
+ *      If the family driver is used for the source files of a \c printf
+ *      mapping, special care must be taken. In this case the VDS code expands
+ *      the file name with \c snprintf first, then the family driver second. This
+ *      means that, while the format specifier for the VDS block number is
+ *      inserted normally, the format specifier for the family file driver
+ *      member number must be escaped such that it is only recognized as a
+ *      format specifier the second time it is run through \c snprintf. As an
+ *      example one may use \TText{%%06d} as the member file number format
+ *      specifier in the source file name.
+ *
  * \par Source File Resolutions:
  *      When a source dataset residing in a different file is accessed, the
  *      library will search for the source file \p src_file_name as described
  *      below:
- *      \li If \p src_file_name is a \TText{"."} (period) then it refers to the
+ *      \li If \p src_file_name is a \TText{.} (period) then it refers to the
  *          file containing the virtual dataset.
  *      \li If \p src_file_name is a relative pathname, the following steps are
  *          performed: