From a290b452b59df320d80fbb5fe7665cb7903a9829 Mon Sep 17 00:00:00 2001 From: Edward Hartnett <38856240+edwardhartnett@users.noreply.github.com> Date: Wed, 15 Nov 2023 10:48:24 -0700 Subject: [PATCH] more documentation changes (#582) --- docs/user_guide.md | 40 ++++++++++++++++------------------------ src/compack.f | 14 ++++---------- src/pngpack.F90 | 16 ++++++++++------ src/pngunpack.F90 | 8 ++++++-- 4 files changed, 36 insertions(+), 42 deletions(-) diff --git a/docs/user_guide.md b/docs/user_guide.md index ee0778c6..62779877 100644 --- a/docs/user_guide.md +++ b/docs/user_guide.md @@ -3,7 +3,7 @@ # Introduction This document briefly describes the routines available for encoding/decoding -GRIB Edition 2 (GRIB2) messages. A basic familiarity with GRIB is assumed. +GRIB Edition 2 (GRIB2) messages. A GRIB Edition 2 message is a machine independent format for storing one or more gridded data fields. Each GRIB2 message consists of the @@ -31,11 +31,6 @@ of the experimental GRIB Edition 2 form. # GRIB2 Encoding Routines -Since a GRIB2 message can contain gridded fields for many parameters on -a number of different grids, several routines are used to encode a message. -This should give users more flexibility in how to organize data -within one or more GRIB2 messages. - To start a new GRIB2 message, call subroutine gribcreate(). It encodes Sections 0 and 1 at the beginning of the message. This routine must be used to create each message. @@ -53,28 +48,24 @@ which adds Sections 4, 5, 6, and 7 to the message. After all desired data fields have been added to the GRIB2 message, a call to routine gribend() is needed to add the final section 8 to the -message and to update the length of the message. A call to GRIBEND() -is required for each GRIB2 message. +message and to update the length of the message. # GRIB2 Decoding Routines -Subroutine gb_info() can be used to find out how many Local Use sections -and data fields are contained in a given GRIB2 message. In addition, -this routine also returns the number of octets of the largest Local Use -section in the message. This value can be used to ensure that the -output array of subroutine GETLOCAL() (described below) is dimensioned -large enough. +Subroutine gb_info() can be used to find out how many Local Use +sections and data fields are contained in a given GRIB2 message. This +routine also returns the number of octets of the largest Local Use +section in the message. This value can be used to ensure that the +output array of subroutine getlocal() is dimensioned large enough. Subroutine getlocal() will return the requested occurrence of Section 2 from a given GRIB2 message. -GF_GETFLD can be used to get all information pertaining to the nth +gf_getfld() can be used to get all information pertaining to the any data field in the message. The subroutine returns all the unpacked values for each Section and Template in a Fortran 90 derived type -gribfield, which is defined in module GRIB_MOD. An option exists that -lets the user decide if the subroutine should unpack the Bit-map (if -applicable) and the data values or just return the field description -information. +grib_mod::gribfield, defined in gribmod.F90. The subroutine may also +unpack the Bit-map and the data values. Note that derived type gribfield contains pointers to dynamically allocated memory; callers must free this memory by calling subroutine @@ -86,17 +77,18 @@ Subroutine getgb2() can be used to extract a specified field from a file containing many GRIB2 messages. getgb2() searches an index to find the location of the user specified field. The index can be supplied from a seperate GRIB2 index file, or it can be generated -internally. If getgb2() is used, call gf_finalize() to free all +internally. + +If getgb2() is used, call gf_finalize() to free all memory. gf_finalize() only needs to be called once, no matter how many times getgb2() is called. The GRIB2 file (and the index file, if supplied) must be opened with a call to subroutine baopen() prior to the call to getgb2(). -The decoded information for the selected GRIB field is returned 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. +The decoded information for the selected GRIB field is returned in a +derived type variable, gfld. Gfld is of type grib_mod::gribfield; +callers will need to include the line "use grib_mod". Note that derived type gribfield contains pointers to many arrays of data. The memory for these arrays is allocated when the values in the arrays diff --git a/src/compack.f b/src/compack.f index 732c4b9f..4a10e103 100644 --- a/src/compack.f +++ b/src/compack.f @@ -1,20 +1,14 @@ !> @file !> @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). +!> Template5.2](https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_temp5-2.shtml) +!> and [Data Representation Template 5.3](https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_temp5-3.shtml). !> @author Stephen Gilbert @date 2000-06-21 !> 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). +!> Template 5.2](https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_temp5-2.shtml) +!> and [Data Representation Template 5.3](https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_temp5-3.shtml). !> !> It also fills in Data Representation Template 5.2 or 5.3 with !> the appropriate values. diff --git a/src/pngpack.F90 b/src/pngpack.F90 index 1b6ea9b2..c541a2f8 100644 --- a/src/pngpack.F90 +++ b/src/pngpack.F90 @@ -1,12 +1,16 @@ !> @file -!> @brief This subroutine packs up a data field into PNG image format. +!> @brief Pack a data field into PNG image format, 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-21 -!> This subroutine packs up a data field into PNG image format. After -!> the data field is scaled, and the reference value is subtracted out, -!> it is treated as a grayscale image and passed to a PNG encoder. It -!> also fills in GRIB2 Data Representation Template 5.41 or 5.40010 -!> with the appropriate values. +!> Pack a data field into PNG image format, defined in [Data +!> Representation Template +!> 5.41](https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_temp5-41.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 +!> PNG encoder. It also fills in GRIB2 Data Representation Template +!> 5.41 or 5.40010 with the appropriate values. !> !> @param[in] fld Contains the data values to pack. !> @param[in] width number of points in the x direction. diff --git a/src/pngunpack.F90 b/src/pngunpack.F90 index a0dc87d6..52e8d53f 100644 --- a/src/pngunpack.F90 +++ b/src/pngunpack.F90 @@ -1,8 +1,12 @@ !> @file -!> @brief Unpack a data field packed into a PNG image format. +!> @brief Unpack a data field with PNG, 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 2000-06-21 -!> Unpack a data field packed into a PNG image format. +!> Unpack a data field with PNG, 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 !> PNG image format using info from the GRIB2 Data Representation