documentation improvements

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/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/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

src/simunpack.F90

@@ -1,11 +1,13 @@
 !> @file
-!> @brief This subroutine packs up a data field.
+!> @brief Unpack a data field that was packed using a simple packing, [Data
+!> Representation Template
+!> 5.0](https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_temp5-0.shtml).
 !> @author Stephen Gilbert @date 2000-06-21
 !>
 
-!> This subroutine unpacks a data field that was packed using a simple
-!> packing algorithm as defined in the GRIB2 documention, using info
-!> from the GRIB2 Data Representation Template 5.0.
+!> Unpack a data field that was packed using a simple packing, [Data
+!> Representation Template
+!> 5.0](https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_temp5-0.shtml).
 !>    
 !> @param[in] cpack The packed data field (character*1 array).
 !> @param[in] len length of packed field cpack.

src/specpack.F90

@@ -1,10 +1,13 @@
 !> @file
-!> @brief This subroutine packs up a spectral data field.
+!> @brief Pack a spectral data field using the complex
+!> packing algorithm for spherical harmonic data as defined in 
+!> [Data Representation Template
+!> 5.51](https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_temp5-51.shtml).
 !> @author Stephen Gilbert @date 2002-12-19
 
-!> This subroutine packs a spectral data field using the complex
-!> packing algorithm for spherical harmonic data as defined in the
-!> GRIB2 [Data Representation Template
+!> Pack a spectral data field using the complex
+!> packing algorithm for spherical harmonic data as defined in 
+!> [Data Representation Template
 !> 5.51](https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_temp5-51.shtml).
 !>
 !> @param[in] fld Contains the data values to pack.

src/specunpack.F90

@@ -1,24 +1,24 @@
-!>    @file
-!>    @brief This subroutine packs up a data field.
-!>    @author Stephen Gilbert @date 2002-12-19
+!> @file
+!> @brief Unpack a spectral data field using the complex packing algorithm
+!> for spherical harmonic data, [Data Representation Template
+!> 5.51](https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_temp5-51.shtml).
+!> @author Stephen Gilbert @date 2002-12-19
 
-!>    This subroutine unpacks a spectral data field that was packed
-!>    using the complex packing algorithm for spherical harmonic data as
-!>    defined in the GRIB2 documention, using info from the GRIB2 [Data
-!>    Representation Template
-!>    5.51](https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_temp5-51.shtml).
+!> Unpack a spectral data field using the complex packing algorithm
+!> for spherical harmonic data, [Data Representation Template
+!> 5.51](https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_temp5-51.shtml).
 !>
-!>    @param[in] cpack The packed data field (character*1 array).
-!>    @param[in] len length of packed field cpack.
-!>    @param[in] idrstmpl Contains the array of values for Data
-!>    Representation Template 5.51.
-!>    @param[in] ndpts The number of data values in array fld.
-!>    @param[in] JJ J pentagonal resolution parameter.
-!>    @param[in] KK K pentagonal resolution parameter.
-!>    @param[in] MM M pentagonal resolution parameter.
-!>    @param[out] fld Contains the unpacked data values.
+!> @param[in] cpack The packed data field (character*1 array).
+!> @param[in] len length of packed field cpack.
+!> @param[in] idrstmpl Contains the array of values for Data
+!> Representation Template 5.51.
+!> @param[in] ndpts The number of data values in array fld.
+!> @param[in] JJ J pentagonal resolution parameter.
+!> @param[in] KK K pentagonal resolution parameter.
+!> @param[in] MM M pentagonal resolution parameter.
+!> @param[out] fld Contains the unpacked data values.
 !>
-!>    @author Stephen Gilbert @date 2002-12-19
+!> @author Stephen Gilbert @date 2002-12-19
 subroutine specunpack(cpack,len,idrstmpl,ndpts,JJ,KK,MM,fld)
 
   character(len=1),intent(in) :: cpack(len)