header files and documentation reorganized and reviewed

src/include/H5Block_attribs.h

@@ -22,10 +22,20 @@
    @{
 */
 
-#ifdef __cplusplus
-extern "C" {
-#endif
-
+/*
+  !   __ _      _     _         _   _        _ _           _            
+  !  / _(_) ___| | __| |   __ _| |_| |_ _ __(_) |__  _   _| |_ ___  ___ 
+  ! | |_| |/ _ \ |/ _` |  / _` | __| __| '__| | '_ \| | | | __/ _ \/ __|
+  ! |  _| |  __/ | (_| | | (_| | |_| |_| |  | | |_) | |_| | ||  __/\__ \
+  ! |_| |_|\___|_|\__,_|  \__,_|\__|\__|_|  |_|_.__/ \__,_|\__\___||___/
+  !
+  !
+  !   __ _ _   _  ___ _ __ _   _ 
+  !  / _` | | | |/ _ \ '__| | | |
+  ! | (_| | |_| |  __/ |  | |_| |
+  !  \__, |\__,_|\___|_|   \__, |
+  !     |_|                |___/ 
+ */
 /**
   Query the number of attributes of field \c field_name.
 
@@ -88,7 +98,14 @@ H5BlockGetFieldAttribInfo (
 			attrib_nelem));
 }
 
-/********************** reading and writing attribute ************************/
+/*
+  !  _    __          _        _             
+  ! (_)  / /__    ___| |_ _ __(_)_ __   __ _ 
+  ! | | / / _ \  / __| __| '__| | '_ \ / _` |
+  ! | |/ / (_) | \__ \ |_| |  | | | | | (_| |
+  ! |_/_/ \___/  |___/\__|_|  |_|_| |_|\__, |
+  !                                    |___/
+*/
 
 /**
   Write the string in \c buffer as attribute \c attrib_name of field
@@ -155,6 +172,13 @@ H5BlockReadFieldAttribString (
 			(void*)buffer));
 }
 
+/*
+  !  _    __                     _ 
+  ! (_)  / /__    _ __ ___  __ _| |
+  ! | | / / _ \  | '__/ _ \/ _` | |
+  ! | |/ / (_) | | | |  __/ (_| | |
+  ! |_/_/ \___/  |_|  \___|\__,_|_|
+ */
 
 /**
   Write float64 \c values as attribute \c attrib_name of field
@@ -267,6 +291,15 @@ H5BlockReadFieldAttribFloat32 (
 			       buffer ));
 }
 
+/*
+  !  _    __      _       _                       
+  ! (_)  / /__   (_)_ __ | |_ ___  __ _  ___ _ __ 
+  ! | | / / _ \  | | '_ \| __/ _ \/ _` |/ _ \ '__|
+  ! | |/ / (_) | | | | | | ||  __/ (_| |  __/ |   
+  ! |_/_/ \___/  |_|_| |_|\__\___|\__, |\___|_|   
+  !                               |___/
+*/
+
 /**
   Write int64 \c values as attribute \c attrib_name of field
   \c field_name.
@@ -376,6 +409,14 @@ H5BlockReadFieldAttribInt32 (
 			       (void*)buffer ));
 }
 
+/*
+  !   __ _      _     _              _       _       
+  !  / _(_) ___| | __| |   ___  _ __(_) __ _(_)_ __  
+  ! | |_| |/ _ \ |/ _` |  / _ \| '__| |/ _` | | '_ \ 
+  ! |  _| |  __/ | (_| | | (_) | |  | | (_| | | | | |
+  ! |_| |_|\___|_|\__,_|  \___/|_|  |_|\__, |_|_| |_|
+  !                                    |___/
+*/
 /**
   Get field origin.
 
@@ -436,6 +477,15 @@ H5Block3dSetFieldOrigin (
 			       3));
 }
 
+/*
+  !   __ _      _     _                        _             
+  !  / _(_) ___| | __| |  ___ _ __   __ _  ___(_)_ __   __ _ 
+  ! | |_| |/ _ \ |/ _` | / __| '_ \ / _` |/ __| | '_ \ / _` |
+  ! |  _| |  __/ | (_| | \__ \ |_) | (_| | (__| | | | | (_| |
+  ! |_| |_|\___|_|\__,_| |___/ .__/ \__,_|\___|_|_| |_|\__, |
+  !                          |_|                       |___/ 
+*/
+
 /**
   Get field spacing for field \c field_name in the current time step.
 
@@ -494,6 +544,13 @@ H5Block3dSetFieldSpacing (
 			       3));
 }
 
+/*
+  !   __ _      _     _                           _     
+  !  / _(_) ___| | __| |   ___ ___   ___  _ __ __| |___ 
+  ! | |_| |/ _ \ |/ _` |  / __/ _ \ / _ \| '__/ _` / __|
+  ! |  _| |  __/ | (_| | | (_| (_) | (_) | | | (_| \__ \
+  ! |_| |_|\___|_|\__,_|  \___\___/ \___/|_|  \__,_|___/
+*/
 /**
   Set an explicit list of X coordinates for field \c field_name in the current
   time step. The coordinates are a 1D array of floating point values with
@@ -557,11 +614,9 @@ H5Block3dGetFieldXCoords (
 
 /**
   Set an explicit list of Y coordinates for field \c field_name in the current
-  time step. The coordinates are a 1D array of floating point values with
-  dimension \c n_coords.
+  time step.
 
-  By convention, the \c coords array should have the same length as the Y
-  dimension of the field, and a warning will be printed if not.
+  \see H5Block3dSetFieldXCoords()
 
   \return \c H5_SUCCESS on success
   \return \c H5_FAILURE on error
@@ -588,11 +643,9 @@ H5Block3dSetFieldYCoords (
 
 /**
   Get the explicit list of Y coordinates for field \c field_name in the current
-  time step. The coordinates are read into the 1D array \c coords which has
-  length \c n_coords.
+  time step.
 
-  By convention, the \c coords array should have the same length as the Y
-  dimension of the field, and a warning will be printed if they differ.
+  \see H5Block3dGetFieldXCoords()
 
   \return \c H5_SUCCESS on success
   \return \c H5_FAILURE on error
@@ -618,11 +671,9 @@ H5Block3dGetFieldYCoords (
 
 /**
   Set an explicit list of Z coordinates for field \c field_name in the current
-  time step. The coordinates are a 1D array of floating point values with
-  dimension \c n_coords.
+  time step.
 
-  By convention, the \c coords array should have the same length as the Z
-  dimension of the field, and a warning will be printed if not.
+  \see H5Block3dSetFieldXCoords()
 
   \return \c H5_SUCCESS on success
   \return \c H5_FAILURE on error
@@ -648,12 +699,10 @@ H5Block3dSetFieldZCoords (
 
 
 /**
-  Get the explicit list of Z coordinates for field \c field_name in the current
-  time step. The coordinates are read into the 1D array \c coords which has
-  length \c n_coords.
+  Get the explicit list of Y coordinates for field \c field_name in the current
+  time step.
 
-  By convention, the \c coords array should have the same length as the Z
-  dimension of the field, and a warning will be printed if they differ.
+  \see H5Block3dGetFieldXCoords()
 
   \return \c H5_SUCCESS on success
   \return \c H5_FAILURE on error
@@ -676,11 +725,5 @@ H5Block3dGetFieldZCoords (
                                f, 2, field_name, H5BLOCK_FIELD_ZCOORD_NAME,
                                coords, n_coords));
 }
-
-#ifdef __cplusplus
-}
-#endif
-
 ///< @}
-
 #endif

src/include/H5Block_io.f90

@@ -7,13 +7,19 @@
 !  License: see file COPYING in top level of source distribution.
 !
   INTERFACE
-     !> \ingroup h5block_f90_api
      !! \addtogroup h5block_io_f
      !! @{
 
      !>
-     !! See \ref H5Block3dWriteScalarFieldFloat64
-     !! \return 0 on success or error code
+     !! Write the 3-dimensional field \p name from the array \p buffer
+     !! to the current step using the previously defined field
+     !! view.
+     !!
+     !! The data type is 64bit floating point (\c REAL*8). Ensure that
+     !! the number of items in the buffer matches the view.
+     !!
+     !! \return \c H5_SUCCESS on success
+     !! \return \c H5_FAILURE on error
 
      INTEGER*8 FUNCTION h5bl_3d_write_scalar_field_r8 ( filehandle, name, buffer )
        INTEGER*8, INTENT(IN) :: filehandle  !< the handle returned at file open
@@ -22,8 +28,14 @@
      END FUNCTION h5bl_3d_write_scalar_field_r8
 
      !>
-     !! See \ref H5Block3dReadScalarFieldFloat64
-     !! \return 0 on success or error code
+     !! Read the 3-dimensional field \c name into the array \p buffer
+     !!from the current step using the previously defined field layout.
+     !!
+     !! The data type is 64bit floating point (\c REAL*8). Ensure that
+     !! the number of items in the buffer matches the view.
+     !!
+     !! \return \c H5_SUCCESS on success
+     !! \return \c H5_FAILURE on error
 
      INTEGER*8 FUNCTION h5bl_3d_read_scalar_field_r8 ( filehandle, name, buffer )
        INTEGER*8, INTENT(IN) :: filehandle  !< the handle returned at file open

src/include/H5Block_io.h

@@ -20,21 +20,15 @@
    @{
 */
 
-#ifdef __cplusplus
-extern "C" {
-#endif
-
 /**
-  Attempts to write the 3-dimensional field \p name from the
-  buffer pointed to by \p buffer to the current step using the
-  previously defined field view. 
+  Write the 3-dimensional field \p name from the buffer pointed to by
+  \p buffer to the current step using the previously defined field
+  view.
 
   The data type is 64bit floating point (\c h5_float64_t). Ensure that
   the number of items in the buffer matches the view.  Use the FORTRAN
   indexing scheme to store data in the buffer.
 
-  You must use the Fortran indexing scheme to access items in \c data.
-
   \return \c H5_SUCCESS on success
   \return \c H5_FAILURE on error
 */
@@ -51,11 +45,12 @@ H5Block3dWriteScalarFieldFloat64 (
 }
 
 /**
-  Read a 3-dimensional field \c name into the buffer starting at \c data from
-  the current time-step using the defined field layout. Values are
-  floating points (64-bit).
+  Read the 3-dimensional field \c name into the buffer pointed to by
+  \p buffer from the current tep using the defined field layout.
 
-  You must use the Fortran indexing scheme to access items in \c data.
+  The data type is 64bit floating point (\c h5_float64_t). Ensure that
+  the number of items in the buffer matches the view.  Use the FORTRAN
+  indexing scheme to access data in the buffer.
 
   \return \c H5_SUCCESS on success
   \return \c H5_FAILURE on error
@@ -74,7 +69,7 @@ H5Block3dReadScalarFieldFloat64 (
 }
 
 /**
-  Write a 3-dimensional field \c name with 3-dimensional vectors as values
+  Write the 3-dimensional field \c name with 3-dimensional vectors as values
   from the buffers starting at \c x_buf, \c y_buf and \c z_buf to the
   current time-step using the defined field layout. Values are 3-dimensional
   vectors with floating points (64-bit) values.
@@ -432,10 +427,5 @@ H5Block3dReadVector3dFieldInt32 (
 					     x_buf, y_buf, z_buf, H5T_NATIVE_INT32));
 }
 
-#ifdef __cplusplus
-}
-#endif
-
 ///< @}
-
 #endif