documentation improvements (#581)

* documentation improvements

* trying to get intel build working

* trying to get intel build working

* trying to get intel build working

* documentation improvements

.github/workflows/Intel.yml

@@ -35,13 +35,14 @@ jobs:
     # See https://software.intel.com/content/www/us/en/develop/articles/oneapi-repo-instructions.html
     - name: install-intel
       run: |
+        set -x
         cd /tmp
         wget https://apt.repos.intel.com/intel-gpg-keys/GPG-PUB-KEY-INTEL-SW-PRODUCTS.PUB
         sudo apt-key add GPG-PUB-KEY-INTEL-SW-PRODUCTS.PUB
         rm GPG-PUB-KEY-INTEL-SW-PRODUCTS.PUB
         echo "deb https://apt.repos.intel.com/oneapi all main" | sudo tee /etc/apt/sources.list.d/oneAPI.list
         sudo apt-get update
-        sudo apt-get install intel-oneapi-dev-utilities intel-oneapi-mpi-devel intel-oneapi-openmp intel-oneapi-compiler-fortran intel-oneapi-compiler-dpcpp-cpp-and-cpp-classic
+        sudo apt-get install intel-oneapi-dev-utilities intel-oneapi-mpi-devel intel-oneapi-compiler-fortran-2023.2.1 intel-oneapi-compiler-dpcpp-cpp-and-cpp-classic-2023.2.1 intel-oneapi-openmp
         echo "source /opt/intel/oneapi/setvars.sh" >> ~/.bash_profile
       
     - name: checkout-bacio
@@ -56,6 +57,7 @@ jobs:
         cd bacio
         mkdir build
         cd build
+        which ifort || which ifx
         ${{ matrix.compilers }} cmake .. -DCMAKE_INSTALL_PREFIX=~/bacio
         make -j2
         make install

src/addfield.f

@@ -1,9 +1,9 @@
 !> @file
-!> @brief Pack up Sections 4 through 7 for a given field and add them
+!> @brief Pack up Sections 4 through 7 for a field and add them
 !> to a GRIB2 message.
 !> @author Stephen Gilbert @date 2000-05-02
 
-!> Pack up Sections 4 through 7 for a given field and add them to a
+!> Pack up Sections 4 through 7 for a field and add them to a
 !> GRIB2 message.
 !>
 !> They are the Product Definition Section, Data Representation

src/compack.f

@@ -1,17 +1,22 @@
 !> @file
-!> @brief This subroutine packs up a GRIB2 data field.
+!> @brief Pack a data field with complex packing with
+!> or without spatial differences defined in [Data Representation
+!> Template5.2 - Grid point data - complex
+!> packing](https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_temp5-2.shtml)
+!> and [Data Representation Template 5.3 - Grid point data - complex
+!> packing and spatial
+!> differencing](https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_temp5-3.shtml).
 !> @author Stephen Gilbert @date 2000-06-21
 
-!> This subroutine supports GRIB2 complex packing templates with or
-!> without spatial differences, Data Representation Templates (DRT)
-!> [GRIB2 - DATA REPRESENTATION TEMPLATE 5.2 - Grid point data -
-!> complex
+!> Pack a data field with complex packing with or
+!> without spatial differences, defined in [Data Representation
+!> Template5.2 - Grid point data - complex
 !> packing](https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_temp5-2.shtml)
-!> and [GRIB2 - DATA REPRESENTATION TEMPLATE 5.3 - Grid point data -
-!> complex packing and spatial
+!> and [Data Representation Template 5.3 - Grid point data - complex
+!> packing and spatial
 !> differencing](https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_temp5-3.shtml).
 !>
-!> It also fills in GRIB2 Data Representation Template 5.2 or 5.3 with
+!> It also fills in Data Representation Template 5.2 or 5.3 with
 !> the appropriate values.
 !>
 !> @param[in] fld The data values to pack.

src/getdim.f

@@ -1,10 +1,10 @@
 !> @file
-!> @brief This subroutine returns the info of GRIB2 Grid Definition
-!> Section 3 format.
+!> @brief Return info from section 3, the GRIB2 Grid Definition
+!> Section.
 !> @author Stephen Gilbert @date 2002-12-11
 
-!> This subroutine returns the dimensions and scanning mode of a grid
-!> definition packed in GRIB2 Grid Definition Section 3 format.
+!> Return the dimensions and scanning mode of a grid
+!> definition packed in the Grid Definition Section.
 !>
 !> @param[in] csec3 Character array that contains the packed GRIB2
 !> GDS.

src/getfield.F90

@@ -1,13 +1,16 @@
 !> @file
-!> @brief Contains subroutines obtain grid information and the
-!> unpacked data (section 3 - 6) for a field from a GRIB2 file.
+!> @brief Return the Grid Definition, Product Definition, Bit-map (if
+!> applicable), and the unpacked data for a data field.
 !> @author Stephen Gilbert @date 2000-05-26
 
-!> This subroutine returns the Grid Definition, Product Definition,
-!> Bit-map (if applicable), and the unpacked data for a given data
-!> field. Since there can be multiple data fields packed into a GRIB2
-!> message, the calling routine indicates which field is being
-!> requested with the ifldnum argument.
+!> Return the Grid Definition, Product Definition, Bit-map (if
+!> applicable), and the unpacked data for a data field. Since there
+!> can be multiple data fields packed into a GRIB2 message, the
+!> calling routine indicates which field is being requested with the
+!> ifldnum argument.
+!>
+!> @note Note that subroutine gribinfo() can be used to first
+!> determine how many data fields exist in a given GRIB message.
 !>
 !> @param[in] cgrib Character array that contains the GRIB2 message.
 !> @param[in] lcgrib Length (in bytes) of GRIB message array cgrib.
@@ -99,9 +102,6 @@
 !> - 13 Error unpacking Section 6.
 !> - 14 Error unpacking Section 7.
 !>
-!> @note Note that subroutine gribinfo can be used to first determine
-!> how many data fields exist in a given GRIB message.
-!>
 !> @author Stephen Gilbert @date 2000-05-26
 subroutine getfield(cgrib, lcgrib, ifldnum, igds, igdstmpl, &
      igdslen, ideflist, idefnum, ipdsnum, ipdstmpl, ipdslen, &

src/getidx.F90

@@ -1,13 +1,12 @@
 !> @file
-!> @brief Find, read or generate a GRIB2 index for the GRIB2 file
-!> associated with unit lugb.
+!> @brief Find, read or generate a GRIB2 index for a GRIB2 file.
 !> @author Stephen Gilbert @date 2005-03-15
 
-!> Find, read or generate a GRIB2 index for the GRIB2 file associated
-!> with unit lugb. If the index already exists, it is returned,
-!> otherwise, the index is (1) read from an existing indexfile
-!> associated with unit lugi or (2) generated from the GRIB2 file
-!> lugb.
+!> @brief Find, read or generate a GRIB2 index for a GRIB2 file.
+!>
+!> If the index already exists in library memory, it is returned,
+!> otherwise, the index is read from an existing indexfile associated
+!> with unit lugi or generated from the GRIB2 file lugb.
 !>
 !> Users can force a regeneration of an index: if lugi equals lugb,
 !> the index will be regenerated from the data in file lugb. If lugi
@@ -22,10 +21,11 @@
 !>
 !> @note The file unit numbers must be in range 1 - 9999.
 !>
-!> @param[in] lugb integer unit of the GRIB2 data file.
-!> File must have been opened with [baopen() or baopenr()]
-!> (https://noaa-emc.github.io/NCEPLIBS-bacio/) before calling
-!> this routine. If 0, then all saved memory will be released.
+!> @param[in] lugb integer unit of the GRIB2 data file.  File must
+!> have been opened with [baopen() or baopenr()]
+!> (https://noaa-emc.github.io/NCEPLIBS-bacio/) before calling this
+!> routine. If 0, then all saved memory will be released (necessary
+!> for g2_finalize()).
 !> @param[in] lugi integer unit of the GRIB2 index file.
 !> If nonzero, file must have been opened with [baopen() or baopenr()]
 !> (https://noaa-emc.github.io/NCEPLIBS-bacio/) before

src/getlocal.F90

@@ -1,10 +1,9 @@
 !> @file
-!> @brief This subroutine returns the contents of Section 2 from a
-!> GRIB2 message.
+!> @brief Return the contents of Section 2 (Local Use) from a GRIB2
+!> message.
 !> @author Stephen Gilbert @date 2000-05-25
 
-!> This subroutine returns the contents of Section 2 from a GRIB2
-!> message.
+!> Return the contents of Section 2 (Local Use) from a GRIB2 message.
 !>
 !> Since there can be multiple occurrences of Section 2 within a GRIB
 !> message, the calling routine indicates which occurrence is being

src/getpoly.f

@@ -1,6 +1,6 @@
 !> @file
-!> @brief Return the J, K, and M pentagonal
-!> resolution parameters specified in a GRIB2 Grid Definition Section.
+!> @brief Return the J, K, and M pentagonal resolution parameters
+!> specified in a GRIB2 Grid Definition Section.
 !> @author Stephen Gilbert @date 2002-12-11
 
 !> Return the J, K, and M pentagonal resolution

src/gettemplates.F90

@@ -1,13 +1,16 @@
 !> @file
-!> @brief This subroutine returns the Grid Definition, and
-!> Product Definition for a given data field.
+!> @brief Return the Grid Definition and Product Definition for a data
+!> field.
 !> @author Stephen Gilbert @date 2000-05-26
 
-!> This subroutine returns the Grid Definition, and Product
-!> Definition for a given data field. Since there can be multiple
-!> data fields packed into a GRIB2 message, the calling routine
-!> indicates which field is being requested with the ifldnum
-!> argument.
+!> Return the Grid Definition and Product Definition for a data field.
+!> Since there can be multiple data fields packed into a GRIB2
+!> message, the calling routine indicates which field is being
+!> requested with the ifldnum argument.
+!>
+!> @note Note that subroutine gribinfo() can be used to first
+!> determine how many data fields exist in a given GRIB message.
+!>
 !> @param[in] cgrib Character array that contains the GRIB2 message
 !> @param[in] lcgrib Length (in bytes) of GRIB message array cgrib.
 !> @param[in] ifldnum Specifies which field in the GRIB2 message to return.
@@ -59,9 +62,6 @@
 !> - 13 Error unpacking Section 6.
 !> - 14 Error unpacking Section 7.
 !>
-!> @note Note that subroutine gribinfo can be used to first determine
-!> how many data fields exist in a given GRIB message.
-!>
 !> @author Stephen Gilbert @date 2000-05-26
 subroutine gettemplates(cgrib, lcgrib, ifldnum, igds, igdstmpl, &
      igdslen, ideflist, idefnum, ipdsnum, ipdstmpl, ipdslen, coordlist, numcoord, ierr)

src/gf_free.F90

@@ -1,5 +1,5 @@
 !> @file
-!> @brief Frees memory in derived type grib_mod::gribfield.
+!> @brief Free memory in derived type grib_mod::gribfield.
 !> @author Stephen Gilbert @date 2000-05-26
 
 !> Free memory that was used to store

src/gf_getfld.F90

@@ -1,14 +1,15 @@
 !> @file
-!> @brief Contains subroutines returns the Grid Definition, and
-!> Product Definition for a given data field.
+!> @brief Return the Grid Definition, and Product Definition for a
+!> given data field.
 !> @author Stephen Gilbert @date 2000-05-26
 
-!> This subroutine returns the Grid Definition, Product Definition,
-!> Bit-map (if applicable), and the unpacked data for a given data
-!> field. All of the information returned is stored in a derived type
-!> variable, gfld. Gfld is of type gribfield, which is defined in
-!> module grib_mod, so users of this routine will need to include the
-!> line "USE GRIB_MOD" in their calling routine.
+!> @brief Return the Grid Definition, and Product Definition for a
+!> given data field.
+!>
+!> All of the information returned is stored in a derived type
+!> variable, gfld. Gfld is of type grib_mod::gribfield, which is
+!> defined in gribmod.F90; users of this routine will need to include
+!> the line "USE GRIB_MOD" in their calling routine.
 !>
 !> Since there can be multiple data fields packed into a GRIB2
 !> message, the calling routine indicates which field is being

src/gribcreate.F90

@@ -1,10 +1,10 @@
 !> @file
-!> @brief This subroutines initializes a new GRIB2 message and packs
-!> GRIB2 Indicator Section and Identification Section.
+!> @brief Initialize a new GRIB2 message and pack GRIB2 sections 0
+!> (Indicator) and 1 (Identification).
 !> @author Stephen Gilbert @date 2000-04-28
 
-!> This subroutine initializes a new GRIB2 message and packs GRIB2
-!> sections 0 (Indicator Section) and 1 (Identification Section).
+!> Initialize a new GRIB2 message and pack GRIB2 sections 0
+!> (Indicator) and 1 (Identification).
 !>
 !> This routine is used with routines addlocal(), addgrid(), addfield(),
 !> and gribend() to create a complete GRIB2 message. Subroutine

src/jpcpack.F90

@@ -1,13 +1,16 @@
 !> @file
-!> @brief Pack a data field into a JPEG2000 code stream.
+!> @brief Pack a data field into a JPEG2000 code stream as defined in
+!> [Data Representation Template
+!> 5.40](https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_temp5-40.shtml).
 !> @author Stephen Gilbert @date 2002-12-17
 
-!> Pack a data field into a JPEG2000 code stream.
+!> Pack a data field into a JPEG2000 code stream as defined in
+!> [Data Representation Template
+!> 5.40](https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_temp5-40.shtml).
 !>
 !> After the data field is scaled, and the reference value is
 !> subtracted out, it is treated as a grayscale image and passed to a
-!> JPEG2000 encoder. It also fills in [GRIB2 - TABLE 5.40 TYPE OF
-!> COMPRESSION](https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_table5-40.shtml).
+!> JPEG2000 encoder. This subroutine also fills in the DRT values.
 !>
 !> @param[in] fld The data values to pack.
 !> @param[in] width number of points in the x direction

src/jpcunpack.F90

@@ -1,8 +1,12 @@
 !> @file
-!> @brief Unpack a data field from a JPEG2000 code stream.
+!> @brief Unpack a data field from a JPEG2000 code stream as defined in
+!> [Data Representation Template
+!> 5.40](https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_temp5-40.shtml).
 !> @author Stephen Gilbert @date 2002-12-17
 
-!> Unpack a data field from a JPEG2000 code stream.
+!> Unpack a data field from a JPEG2000 code stream as defined in
+!> [Data Representation Template
+!> 5.40](https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_temp5-40.shtml).
 !>
 !> This subroutine unpacks a data field that was packed into a
 !> JPEG2000 code stream using info from the GRIB2 Data Representation

src/putgb2.F90

@@ -1,22 +1,23 @@
 !> @file
-!> @brief Packs a single field into a GRIB2 message and
-!> writes out that message to the file.
+!> @brief Pack a field into a GRIB2 message and write the message to a
+!> file.
 !>
 !> @author Stephen Gilbert @date 2002-01-11
 
-!> This subroutine packs a single field into a grib2 message and
-!> writes out that message to the file associated with unit lugb.
-!> Note that file/unit lugb should be opened with a call to subroutine
-!> [baopen() or baopenw()]
-!> (https://noaa-emc.github.io/NCEPLIBS-bacio/) before this routine is
-!> called.
+!> Pack a field into a grib2 message and write that message to a file.
 !>
 !> The information to be packed into the grib field is stored in a
-!> derived type variable, gfld. gfld is of type gribfield, which is
-!> defined in module grib_mod, so users of this routine will need to
-!> include the line "use grib_mod" in their calling routine. Each
-!> component of the gribfield type is described in the input argument
-!> list section below.
+!> derived type variable, gfld. gfld is of type grib_mod::gribfield,
+!> which is defined in module grib_mod, so users of this routine will
+!> need to include the line "use grib_mod" in their calling
+!> routine. Each component of the gribfield type is described in the
+!> input argument list section below.
+!>
+!> @note Derived type gribfield contains pointers to many arrays of
+!> data (See @ref grib_mod::gribfield). The memory for these arrays is
+!> allocated when the values in the arrays are set. Users must free
+!> this memory, when it is no longer needed, by a call to subroutine
+!> gf_free().
 !>
 !> @param[in] lugb integer unit of the unblocked grib data file.  File
 !> must be opened with [baopen() or baopenw()]
@@ -30,12 +31,6 @@
 !> - 11 No Grid Definition Template info available.
 !> - 12 Missing some required data field info.
 !>
-!> @note Derived type gribfield contains pointers to many arrays of
-!> data (See @ref grib_mod::gribfield). The memory for these arrays is
-!> allocated when the values in the arrays are set, to help minimize
-!> problems with array overloading. Users must free up this memory,
-!> when it is no longer needed, by a call to subroutine gf_free().
-!>
 !> @author Stephen Gilbert @date 2002-04-22
 subroutine putgb2(lugb, gfld, iret)
   use grib_mod

src/simpack.f

@@ -1,27 +1,28 @@
-!>    @file
-!>    @brief Pack up a data field using simple packing algorithm.
-!>    @author Stephen Gilbert @date 2000-06-21
+!> @file
+!> @brief Pack a data field using simple packing algorithm.
+!> @author Stephen Gilbert @date 2000-06-21
 
-!>    Pack up a data field using a simple packing
-!>    algorithm as defined in the GRIB2 documention. It also fills in GRIB2
-!>    Data Representation Template 5.0 with the appropriate values.
-!>    
-!>    @param[in] fld Contains the data values to pack.
-!>    @param[in] ndpts The number of data values in array fld.
-!>    @param[inout] idrstmpl Contains the array of values for Data
-!>    Representation Template 5.2 or 5.3.
-!>    - (1) Reference value - ignored on input
-!>    - (2) Binary Scale Factor
-!>    - (3) Decimal Scale Factor
-!>    - (4) Number of bits used to pack data, if value is > 0 and <=
-!>    31. If this input value is 0 or outside above range then the num
-!>    of bits is calculated based on given data and scale factors.
-!>    - (5) Original field type - currently ignored on input Data values
-!>    assumed to be reals.
-!>    @param[out] cpack The packed data field (character*1 array).
-!>    @param[out] lcpack length of packed field cpack.
+!> Pack a data field using a simple packing algorithm.
+!> 
+!> This subroutine also fills in GRIB2 Data Representation Template 5.0
+!> with the appropriate values.
+!> 
+!> @param[in] fld Contains the data values to pack.
+!> @param[in] ndpts The number of data values in array fld.
+!> @param[inout] idrstmpl Contains the array of values for Data
+!> Representation Template 5.2 or 5.3.
+!> - (1) Reference value - ignored on input
+!> - (2) Binary Scale Factor
+!> - (3) Decimal Scale Factor
+!> - (4) Number of bits used to pack data, if value is > 0 and <=
+!> 31. If this input value is 0 or outside above range then the num
+!> of bits is calculated based on given data and scale factors.
+!> - (5) Original field type - currently ignored on input Data values
+!> assumed to be reals.
+!> @param[out] cpack The packed data field (character*1 array).
+!> @param[out] lcpack length of packed field cpack.
 !>
-!>    @author Stephen Gilbert @date 2000-06-21
+!> @author Stephen Gilbert @date 2000-06-21
       subroutine simpack(fld,ndpts,idrstmpl,cpack,lcpack)
       use intmath
       implicit none