improve brief descriptions (#472)

* improve brief descriptions

* improve brief descriptions

* improve documentation

* improve documentation

docs/user_guide.md

@@ -31,7 +31,7 @@ redefined.
 For detailed information on GRIB2 see the [NCEP WMO GRIB2
 Documentation](https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/).
 
-# GRIB2 Encoding Routines
+## 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
@@ -60,7 +60,7 @@ call to routine g2_gribend() is needed to add the final section 8 to the
 message and to update the length of the message. A call to g2_gribend()
 is required for each GRIB2 message.
 
-# GRIB2 Decoding Routines
+## GRIB2 Decoding Routines
 
 Function g2_info() can be used to find out how many Local Use
 sections and data fields are contained in a given GRIB2 message. In
@@ -72,12 +72,12 @@ data field in the message. An option exists that lets the user decide
 if the function should unpack the Bit-map (if applicable) and the
 data values or just return the field description information.
 
-# Extracting GRIB2 Fields from a GRIB2 file
+## Extracting GRIB2 Fields from a GRIB2 file
 
 Function g2_info() can be used to find out how many Local Use
 sections and data fields are contained in a given GRIB2 message.
 
-# GRIB2 Tables/Templates
+## GRIB2 Tables/Templates
 
 NCO Provides documentation on WMO GRIB2 at
 https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/

src/aecpack.c

@@ -17,8 +17,7 @@
 #include "grib2_int.h"
 
 /**
- * This internal function packs up a float or double array into a
- * AEC/CCSDS code stream.
+ * Pack a float or double array into a AEC/CCSDS code stream.
  *
  * @param fld Pointer to the float or double data values to pack.
  * @param fld_is_double If non-zero, then fld points to array of

src/aecunpack.c

@@ -8,7 +8,7 @@
 #include "grib2_int.h"
 
 /**
- * This internal function will unpack AEC compressed data into an
+ * Unpack AEC compressed data into an
  * array of floats or doubles, using info from the GRIB2 Data
  * Representation [Template
  * 5.42](https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_temp5-42.shtml).

src/cmplxpack.c

@@ -1,14 +1,15 @@
 /** @file
- * @brief Pack up a data field using a complex packing
- * algorithm as defined in the GRIB2 documention.
+ * @brief Pack a data field using a complex packing algorithm.
  * @author Stephen Gilbert @date 2004-08-27
  */
 
 #include "grib2_int.h"
 
 /**
- * This subroutine packs up a data field using a complex packing
- * algorithm as defined in the GRIB2 documention. It supports GRIB2
+ * Pack up a data field using a complex packing
+ * algorithm. 
+ *
+ * This function supports GRIB2
  * complex packing templates with or without spatial differences
  * (i.e. DRTs 5.2 and 5.3). It also fills in GRIB2 Data Representation
  * Template 5.2 or 5.3 with the appropriate values.

src/compack.c

@@ -1,7 +1,7 @@
 /**
  * @file
- * @brief Pack up a data field using a complex packing
- * algorithm as defined in the GRIB2 documention.
+ * @brief Pack a data field using a complex packing
+ * algorithm.
  * @author Stephen Gilbert @date 2002-11-07
  */
 
@@ -10,11 +10,11 @@
 #include "grib2_int.h"
 
 /**
- * This subroutine packs up a data field using a complex packing
- * algorithm as defined in the GRIB2 documention. It supports GRIB2
- * complex packing templates with or without spatial differences
- * (i.e. DRTs 5.2 and 5.3). It also fills in GRIB2 Data Representation
- * [Template
+ * Pack a data field using a complex packing algorithm.
+ *
+ * This function supports GRIB2 complex packing templates with or
+ * without spatial differences (i.e. DRTs 5.2 and 5.3). It also fills
+ * in GRIB2 Data Representation [Template
  * 5.2](https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_temp5-2.shtml)
  * or [Template
  * 5.3](https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_temp5-3.shtml)

src/comunpack.c

@@ -8,9 +8,8 @@
 #include "grib2_int.h"
 
 /**
- * This subroutine unpacks a data field that was packed using a
- * complex packing algorithm as defined in the GRIB2 documention,
- * using info from the GRIB2 Data Representation [Template
+ * Unpack a data field that was packed using a complex packing
+ * algorithm, using info from the GRIB2 Data Representation [Template
  * 5.2](https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_temp5-2.shtml)
  * or [Template
  * 5.3](https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_temp5-3.shtml).

src/dec_jpeg2000.c

@@ -1,12 +1,6 @@
 /** @file
  * @brief Decodes JPEG2000 code stream.
  * @author Stephen Gilbert @date 2002-12-02
- *
- * ### Program History Log
- * Date | Programmer | Comments
- * -----|------------|---------
- * 2002-12-02 | Gilbert | Initial
- * 2022-04-15 | Hartnett | Converted to use jas_ instead of jpc_ functions.
  */
 
 #include <stdio.h>
@@ -16,7 +10,7 @@
 #include "jasper/jasper.h"
 
 /**
- * This Function decodes a JPEG2000 code stream specified in the
+ * Decode a JPEG2000 code stream specified in the
  * JPEG2000 Part-1 standard (i.e., ISO/IEC 15444-1) using [JasPer
  * Software](https://github.com/jasper-software/jasper).
  *
@@ -150,7 +144,7 @@ int_dec_jpeg2000(char *injpc, g2int bufsize, void *outfld, int out_is_g2int)
 }
 
 /**
- * This Function decodes a JPEG2000 code stream specified in the
+ * Decode a JPEG2000 code stream specified in the
  * JPEG2000 Part-1 standard (i.e., ISO/IEC 15444-1) using [JasPer
  * Software](https://github.com/jasper-software/jasper).
  *
@@ -177,7 +171,7 @@ g2c_dec_jpeg2000(char *injpc, size_t bufsize, int *outfld)
 }
 
 /**
- * This Function decodes a JPEG2000 code stream specified in the
+ * Decode a JPEG2000 code stream specified in the
  * JPEG2000 Part-1 standard (i.e., ISO/IEC 15444-1) using [JasPer
  * Software](https://github.com/jasper-software/jasper).
  *

src/decenc_aec.c

@@ -1,12 +1,6 @@
 /** @file
- * @brief Decode and encode functions for AEC compression.
- * stream
+ * @brief Decode/encode an AEC code stream.
  * @author Eric Engle @date 2023-10-16
- *
- * Program History Log
- * Date | Programmer | Comments
- * -----|------------|---------
- * 2023-10-16 | Engle | Initial
  */
 
 #include <stdio.h>
@@ -15,8 +9,8 @@
 #include "grib2_int.h"
 
 /**
- * This Function decodes an AEC code stream specified in the
- * [CCSDS 121.0-B-3 Blue Book](https://public.ccsds.org/Pubs/121x0b3.pdf).
+ * Decode an AEC code stream specified in the [CCSDS 121.0-B-3 Blue
+ * Book](https://public.ccsds.org/Pubs/121x0b3.pdf).
  *
  * @param cpack Pointer to buffer that holds the input AEC code
  * stream.
@@ -84,7 +78,7 @@ int dec_aec(unsigned char *cpack, g2int len, g2int nbits, g2int flags,
 }
 
 /**
- * This Function encodes data into an AEC code stream specified in the
+ * Encode data into an AEC code stream specified in the
  * [CCSDS 121.0-B-3 Blue Book](https://public.ccsds.org/Pubs/121x0b3.pdf).
  *
  * @param data Pointer to buffer that holds the input data.

src/decenc_openjpeg.c

@@ -1,8 +1,9 @@
 /**
  * @file
  * @brief JPEG functions, originally from ECMWF, modified for use in NCEPLIBS-g2c.
- *
- * Copyright 2005-2019 ECMWF.
+ * @author ECMWF programmer
+ */
+/* Copyright 2005-2019 ECMWF.
  *
  * This software is licensed under the terms of the Apache Licence
  * Version 2.0 which can be obtained at
@@ -12,8 +13,6 @@
  * immunities granted to it by virtue of its status as an
  * intergovernmental organisation nor does it submit to any
  * jurisdiction.
- *
- * @author ECMWF programmer
  */
 
 #if !defined USE_JPEG2000 && defined USE_OPENJPEG

src/drstemplates.c

@@ -1,7 +1,7 @@
 /**
  * @file
- * @brief Functions for GRIB2 Data Representation Templates (DRT) for
- * the Data Representation Setcion.
+ * @brief Functions, Structures, and Data for Data Representation
+ * Templates (DRT).
  *
  * Each Template has three parts:
  * 1. The number of entries in the template (mapdrslen).

src/enc_jpeg2000.c

@@ -1,5 +1,13 @@
 /** @file
  * @brief Encodes JPEG2000 code stream.
+ *
+ * ### Program History Log
+ * Date | Programmer | Comments
+ * -----|------------|---------
+ * 2002-12-02 | Gilbert | Initial
+ * 2004-12-16 | Gilbert | Added retry argument allowing increased guard bits.
+ * 2022-04-15 | Hartnett | Converted to use jas_ instead of jpc_ functions.
+ *
  * @author Stephen Gilbert @date 2002-12-02
  */
 
@@ -11,17 +19,10 @@
 #define MAXOPTSSIZE 1024 /**< Maximum size of options. */
 
 /**
- * This Function encodes a grayscale image into a JPEG2000 code stream
+ * Encode a grayscale image into a JPEG2000 code stream
  * specified in the JPEG2000 Part-1 standard (i.e., ISO/IEC 15444-1)
  * using [JasPer Software](https://github.com/jasper-software/jasper).
  *
- * ### Program History Log
- * Date | Programmer | Comments
- * -----|------------|---------
- * 2002-12-02 | Gilbert | Initial
- * 2004-12-16 | Gilbert | Added retry argument allowing increased guard bits.
- * 2022-04-15 | Hartnett | Converted to use jas_ instead of jpc_ functions.
- *
  * @param cin Packed matrix of Grayscale image values to encode.
  * @param width width of image.
  * @param height height of image.
@@ -60,17 +61,10 @@ g2c_enc_jpeg2000(unsigned char *cin, int width, int height, int nbits,
 }
 
 /**
- * This Function encodes a grayscale image into a JPEG2000 code stream
+ * Encode a grayscale image into a JPEG2000 code stream
  * specified in the JPEG2000 Part-1 standard (i.e., ISO/IEC 15444-1)
  * using [JasPer Software](https://github.com/jasper-software/jasper).
  *
- * ### Program History Log
- * Date | Programmer | Comments
- * -----|------------|---------
- * 2002-12-02 | Gilbert | Initial
- * 2004-12-16 | Gilbert | Added retry argument allowing increased guard bits.
- * 2022-04-15 | Hartnett | Converted to use jas_ instead of jpc_ functions.
- *
  * @param cin Packed matrix of Grayscale image values to encode.
  * @param width width of image.
  * @param height height of image.

src/g2_addfield.c

@@ -1,5 +1,5 @@
 /** @file
- * @brief Pack up Sections 4 through 7 for a given field and adds them
+ * @brief Pack sections 4 through 7 and add them
  * to a GRIB2 message.
  * @author Stephen Gilbert @date 2002-11-05
  */
@@ -9,16 +9,17 @@
 #include "grib2_int.h"
 
 /**
- * This routine packs up Sections 4 through 7 for a given field and
- * adds them to a GRIB2 message. They are [Product Definition
- * Section](https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_sect4.shtml),
- * [Data Representation
- * Section](https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_sect5.shtml),
- * [Bit-Map
+ * Pack sections 4 through 7 and adds them to a GRIB2 message.
+ *
+ * They are:
+ * 4. [Product Definition
+ * Section](https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_sect4.shtml)
+ * 5. [Data Representation
+ * Section](https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_sect5.shtml)
+ * 6. [Bit-Map
  * Section](https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_sect6.shtml)
- * and [Data
- * Section](https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_sect7.shtml),
- * respectively.
+ * 7. [Data
+ * Section](https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_sect7.shtml)
  *
  * This routine is used with routines g2_create(), g2_addlocal(),
  * g2_addgrid(), and g2_gribend() to create a complete GRIB2

src/g2_addgrid.c

@@ -1,6 +1,6 @@
 /**
  * @file
- * @brief Pack up a Grid Definition Section (Section 3) and adds it to
+ * @brief Pack a Grid Definition Section (Section 3) and adds it to
  * a GRIB2 message.
  * @author Stephen Gilbeert @date 2002-11-01
  */
@@ -10,19 +10,15 @@
 #include "grib2_int.h"
 
 /**
- * This routine packs up a [Grid Definition Section (Section
+ * Packs a [Grid Definition Section (Section
  * 3)](https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_sect3.shtml)
- * and adds it to a GRIB2 message. It is used with routines
+ * and adds it to a GRIB2 message. 
+ *
+ * This function is used with routines
  * g2_create(), g2_addlocal(), g2_addfield(), and g2_gribend() to
  * create a complete GRIB2 message. g2_create() must be called first
  * to initialize a new GRIB2 message.
  *
- * ### Program History Log
- * Date | Programmer | Comments
- * -----|------------|---------
- * 2002-11-01 | Gilbert | Initial.
- * 2009-01-14 | Vuong | Changed structure name template to gtemplate
- *
  * @param cgrib Char array that contains the GRIB2 message to which
  * section should be added. Must be allocated large enough to store
  * the entire GRIB2 message.

src/g2_addlocal.c

@@ -7,11 +7,12 @@
 #include "grib2_int.h"
 
 /**
- * This routine adds a [Local Use Section (Section
+ * Adds a [Local Use Section (Section
  * 2)](https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_sect2.shtml)
- * to a GRIB2 message. It is used with routines g2_create(),
- * g2_addgrid(), g2_addfield(), and g2_gribend() to create a complete
- * GRIB2 message.
+ * to a GRIB2 message. 
+ *
+ * This function is used with routines g2_create(), g2_addgrid(),
+ * g2_addfield(), and g2_gribend() to create a complete GRIB2 message.
  *
  * @param cgrib Char array that contains the GRIB2 message to which
  * section 2 should be added. Must be allocated large enough to store

src/g2_create.c

@@ -1,5 +1,5 @@
 /** @file
- * @brief Initializes a new GRIB2 message and packs GRIB2 sections 0
+ * @brief Initialize a new GRIB2 message and pack GRIB2 sections 0
  * (Indicator Section) and 1 (Identification Section).
  * @author Stephen Gilbert @date 2002-10-31
  */
@@ -11,7 +11,7 @@
 #define LENSEC0 16 /**< Length of GRIB Section 0. */
 
 /**
- * This routine initializes a new GRIB2 message and packs GRIB2
+ * Initialize a new GRIB2 message and pack GRIB2
  * [Section 0 (Indicator
  * Section)](https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_sect0.shtml)
  * and [Section 1 (Identification

src/g2_free.c

@@ -1,17 +1,16 @@
 /**
  * @file
- * @brief Free up memory that was allocated for struct gribfield.
+ * @brief Free up memory that was allocated for struct ::gribfield.
  * @author Stephen Gilbeert @date 2002-10-28
  */
 
 #include <stdlib.h>
 #include  "grib2_int.h"
 
 /**
- * This routine frees up memory that was allocated for struct
- * gribfield.
+ * Free memory that was allocated for struct ::gribfield.
  *
- * @param gfld pointer to gribfield structure (defined in include file
+ * @param gfld pointer to ::gribfield structure (defined in include file
  * grib2.h) returned from routine g2_getfld().
  *
  * @note This routine must be called to free up memory used by the