Merge pull request #531 from NOAA-EMC/jba_docfixes

documentation updates

docs/dx_tables.md

@@ -312,8 +312,7 @@ within the definition of the Table D sequence mnemonic OBSEQ as well
 as each occurrence of HINC within the definition of the Table A
 mnemonic NC002007. This indicator is called an <i>operator</i>, and
 readers more familiar with the details of BUFR will no doubt recognize
-it from Table C of the [official WMO master BUFR tables](@ref
-wmomstab).
+it from Table C of the [official WMO master BUFR tables](@ref wmomstab).
 
 <br>
 

src/ardllocc.c

@@ -9,9 +9,7 @@
 #include "mstabs.h"
 
 /**
- * Free all dynamically-allocated memory within internal C language arrays.
- *
- * This subroutine frees any memory that was dynamically allocated
+ * Free all memory that was dynamically allocated
  * during a previous call to subroutine arallocc().
  *
  * @author J. Ator @date 2014-12-04

src/ardllocf.f

@@ -4,7 +4,7 @@
 C>
 C> @author J. Ator @date 2014-12-04
 
-C> This subroutine frees any memory that was dynamically allocated
+C> Free all memory that was dynamically allocated
 C> during a previous call to subroutine arallocf().
 C>
 C> @author J. Ator @date 2014-12-04

src/atrcpt.f

@@ -2,7 +2,7 @@
 C> @brief Add a tank receipt time to a BUFR message.
 C> @author J. Ator @date 2009-03-23
 
-C> This subroutine reads an input message and outputs an equivalent
+C> Read an input message and output an equivalent
 C> BUFR message with a tank receipt time added to Section 1.
 C>
 C> The tank receipt time to be added must have been specified via

src/bfrini.f90.in

@@ -2,8 +2,8 @@
 !> @brief Initialize global variables and arrays within internal memory.
 !> @authors J. Woollen J. Ator @date 1994-01-06
 
-!> This subroutine initializes numerous global variables and arrays
-!> within internal modules and COMMON blocks throughout the BUFRLIB
+!> Initialize numerous global variables and arrays
+!> within internal modules and COMMON blocks throughout the NCEPLIBS-bufr
 !> software.
 !>
 !> This subroutine isn't normally called directly by any application

src/blocks.f

@@ -3,7 +3,7 @@
 C> words.
 C> @author J. Woollen @date 2012-09-15
 
-C> This subroutine encapsulates a BUFR message with IEEE Fortran
+C> Encapsulate a BUFR message with IEEE Fortran
 C> control words as specified via the most recent call to
 C> subroutine setblock().
 C>
@@ -20,7 +20,6 @@
 C> called, or if no encapsulation was specified during the most
 C> recent call to subroutine setblock(), then this subroutine
 C> simply returns without modifying either of its input parameters.
-C> @date 2012-09-15
 C>
 C> @param[in,out] MBAY -- integer(*): BUFR message, possibly with
 C>                        added control words on output
@@ -29,7 +28,7 @@
 C>
 C> @remarks
 C> - For more information about IEEE Fortran control words, as
-C> well as their historical use within the BUFRLIB software, see
+C> well as their historical use within the NCEPLIBS-bufr software, see
 C> the documentation for subroutine setblock().
 C> - Whenever a BUFR message in MBAY is to be encapsulated with
 C> control words, the user must ensure the availability of

src/bort.f

@@ -3,12 +3,10 @@
 C>
 C> @author J. Woollen @date 1998-07-08
 
-C> Log one error message and abort application program.
+C> Call subroutine errwrt() to log an error message,
+C> then call subroutine bort_exit() to abort the application program.
 C>
-C> This subroutine calls subroutine errwrt() to log an error message,
-C> then calls subroutine bort_exit() to abort the application program.
-C>
-C> It is similar to subroutine bort2(), except that bort2() logs
+C> This subroutine is similar to subroutine bort2(), except that bort2() logs
 C> two error messages instead of one.
 C>
 C> @param[in] STR - character*(*): Error message

src/bort2.f

@@ -2,12 +2,10 @@
 C> @brief Log two error messages and abort application program.
 C> @author D. Keyser @date 2003-11-04
 
-C> Log two error messages and abort application program.
+C> Call subroutine errwrt() to log two error messages,
+C> then call subroutine bort_exit() to abort the application program.
 C>
-C> This subroutine calls subroutine errwrt() to log two error messages,
-C> then calls subroutine bort_exit() to abort the application program.
-C>
-C> It is similar to subroutine bort(), except that bort() logs
+C> This subroutine is similar to subroutine bort(), except that bort() logs
 C> one error message instead of two.
 C>
 C> @param[in] STR1 - character*(*): First error message

src/bort_exit.c

@@ -6,8 +6,7 @@
 #include "bufrlib.h"
 
 /**
- * This subroutine terminates the application program with
- * a non-zero status code.
+ * Terminate the application program with a non-zero status code.
  *
  * @author J. Ator @date 2003-11-04
  */

src/bufr_c2f_interface.F90

@@ -779,7 +779,7 @@ end subroutine elemdx_c
     !> Wraps numtbd() subroutine.
     !>
     !> @param lun - File ID.
-    !> @param idn - Bit-wise representation of FXY value.
+    !> @param idn - WMO bit-wise representation of FXY value.
     !> @param nemo - Mnemonic.
     !> @param nemo_str_len - Length of nemo string.
     !> @param tab - Type of internal DX BUFR table ('B', or 'D').

src/bufrlib.F90

@@ -182,19 +182,19 @@ end subroutine ardllocc_c
     !> Wraps cpmstabs() function.
     !>
     !> @param nmtb - Number of master Table B entries.
-    !> @param ibfxyn - Bit-wise representations of master Table B FXY numbers.
+    !> @param ibfxyn - WMO bit-wise representations of master Table B FXY numbers.
     !> @param cbscl - Master Table B scale factors.
     !> @param cbsref - Master Table B reference values.
     !> @param cbbw - Master Table B bit widths.
     !> @param cbunit - Master Table B units.
     !> @param cbmnem - Master Table B mnemonics.
     !> @param cbelem - Master Table B element names.
     !> @param nmtd - Number of master Table D entries.
-    !> @param idfxyn - Bit-wise representations of master Table D FXY numbers.
+    !> @param idfxyn - WMO bit-wise representations of master Table D FXY numbers.
     !> @param cdseq - Master Table D sequence names.
     !> @param cdmnem - Master Table D mnemonics.
     !> @param ndelem - Number of child descriptors for master Table D sequence.
-    !> @param idefxy - Bit-wise representations of child descriptors for master Table D sequence.
+    !> @param idefxy - WMO bit-wise representations of child descriptors for master Table D sequence.
     !> @param maxcd - Maximum number of child descriptors for a master Table D sequence.
     !>
     !> @author J. Ator @date 2005-11-29
@@ -222,12 +222,12 @@ end subroutine inittbf_c
     !>
     !> Wraps strtbfe() function.
     !>
-    !> @param ifxyn - Bit-wise representation of FXY number for which ival is a defined
+    !> @param ifxyn - WMO bit-wise representation of FXY number for which ival is a defined
     !> code or flag table entry.
     !> @param ival  - Code figure or bit number.
     !> @param meaning - Meaning associated with ifxyn and ival.
     !> @param lmeaning - Length (in bytes) of meaning.
-    !> @param idfxy - Bit-wise representation of FXY number upon which ifxyn and ival
+    !> @param idfxy - WMO bit-wise representation of FXY number upon which ifxyn and ival
     !> depend (if any), or else set to a value of (-1).
     !> @param idval - Code figure or bit number associated with idfxy and upon which ifxyn
     !> and ival depend (if any), or else set to (-1) whenever idfxy is also set to (-1).
@@ -254,17 +254,17 @@ end subroutine sorttbf_c
     !>
     !> Wraps srchtbf() function.
     !>
-    !> @param ifxyi - Bit-wise representation of FXY number to search for.
+    !> @param ifxyi - WMO bit-wise representation of FXY number to search for.
     !> @param ivali - Value (code figure or bit number) associated with ifxyi.
     !> @param ifxyd - Dependence indicator:
-    !> - On input, ifxyd[0] is set to the bit-wise representation of the FXY
+    !> - On input, ifxyd[0] is set to the WMO bit-wise representation of the FXY
     !> number upon which ifxyi and ivali depend, or else set to (-1) if ifxyi
     !> and ivali do not depend on the value associated with any other FXY number.
     !> - On output, if the initial search of the master Code/Flag table was
     !> unsuccessful, <b>and</b> if ifxyd[0] and ivald were both set to (-1) on
     !> input, <b>and</b> if a second search of the table determines that the
     !> meaning of ifxyi and ivali indeed depends on one or more other FXY numbers,
-    !> then the bit-wise representations of those FXY numbers are returned within
+    !> then the WMO bit-wise representations of those FXY numbers are returned within
     !> the first iret elements of ifxyd.
     !> @param ivald - Value (code figure or bit number) associated with the FXY
     !> number in ifxyd[0]; set to (-1) whenever ifxyd[0] is also set to (-1).
@@ -280,7 +280,7 @@ end subroutine sorttbf_c
     !> - -1 = Meaning not found.
     !> - >0 = Meaning not found, <b>and</b> ifxyd[0] and ivald were both set to (-1)
     !> on input, <b>and</b> the meaning of ifxyi and ivali depends on the the value
-    !> associated with one of the FXY numbers whose bit-wise representation is
+    !> associated with one of the FXY numbers whose WMO bit-wise representation is
     !> stored in the first iret elements of ifxyd.
     !>
     !> @author J. Ator @date 2017-11-03

src/bufrlib.h.in

@@ -118,7 +118,7 @@ void elemdx_f(char *card, int lun);
  * Wraps numtbd() subroutine.
  *
  * @param lun - File ID.
- * @param idn - Bit-wise representation of FXY value.
+ * @param idn - WMO bit-wise representation of FXY value.
  * @param nemo - Mnemonic.
  * @param nemo_str_len - Length of nemo string.
  * @param tab - Type of internal DX BUFR table ('B', or 'D').

src/bvers.f.in

@@ -3,9 +3,7 @@ C> @brief Get the version number of the NCEPLIBS-bufr software.
 C>
 C> @author J. Ator @date 2009-03-23
 
-C> Get the version number of the NCEPLIBS-bufr software.
-C>
-C> This subroutine returns a character string containing
+C> Return a character string containing
 C> the version number of the NCEPLIBS-bufr software.
 C>
 C> @param[out] CVERSTR - character*(*): Version string.

src/cadn30.f

@@ -4,11 +4,10 @@
 C>
 C> @author J. Ator @date 2004-08-18
 
-C> Convert an FXY value from its WMO bit-wise representation
-C> to its six-character representation.
+C> Convert an FXY value from its WMO bit-wise
+C> representation to its 6 character representation.
 C>
-C> This subroutine converts an FXY value from its WMO bit-wise
-C> representation to its 6 character representation.  It is similar
+C> This subroutine is similar
 C> to function adn30(), except that it always returns 6 characters,
 C> and it always returns its output as a call parameter instead of a
 C> function value, which in turn allows it to be more easily called
@@ -17,7 +16,7 @@
 C> For a description of the WMO bit-wise representation of an FXY
 C> value, see ifxy().
 C>
-C> @param[in] IDN - integer: Bit-wise representation of FXY value.
+C> @param[in] IDN - integer: WMO bit-wise representation of FXY value.
 C> @param[out] ADN - character*6: FXY value.
 C>
 C> @author J. Ator @date 2004-08-18

src/capit.f

@@ -3,7 +3,7 @@
 C>
 C> @author J. Woollen @date 2002-05-14
 
-C> This subroutine capitalizes all of the alphabetic characters in
+C> Capitalize all of the alphabetic characters in
 C> a string. The string is modified in place.
 C>
 C> @param[in,out] STR - character*(*): String

src/cfe.c

@@ -14,13 +14,13 @@
  *  Structure to store a master Code/Flag table entry.
  */
 struct code_flag_entry {
-    /** Bit-wise representation of FXY number to which this entry belongs. */
+    /** WMO bit-wise representation of FXY number to which this entry belongs. */
     int iffxyn;
     /** Code figure or bit number. */
     int ifval;
     /** Meaning corresponding to ifval. */
     char ifmeaning[MAX_MEANING_LEN+1];
-    /** Bit-wise representation of FXY number upon which this entry is
+    /** WMO bit-wise representation of FXY number upon which this entry is
      *  dependent, if any.  Set to (-1) if no dependency.
      */
     int iffxynd;
@@ -44,11 +44,8 @@ int mxmtbf;
 int nmtf;
 
 /**
- *  Initialize memory for internal storage of master Code/Flag table entries.
- *
- *  This function initializes the internal memory structure
- *  for storage of master Code/Flag table entries, including
- *  dynamically allocating space for this structure if needed.
+ *  Initialize memory for internal storage of master Code/Flag table entries,
+ *  including dynamically allocating memory space if needed.
  *
  *  @author J. Ator  @date 2017-11-03
 */
@@ -76,8 +73,7 @@ inittbf(void)
 /**
  * Free all dynamically-allocated memory for internal storage of master Code/Flag table entries.
  *
- * This function frees any memory that was dynamically allocated
- * during a previous call to function inittbf().
+ * This memory would have been dynamically allocated during a previous call to function inittbf().
  *
  * @author J. Ator @date 2017-11-03
  */
@@ -92,9 +88,7 @@ dlloctbf(void)
 /**
  * Define a comparison between two master Code/Flag table entries.
  *
- * This function defines a comparison between two entries within the
- * internal memory structure for storage of master Code/Flag table
- * entries.  The comparison is used by the intrinsic C functions
+ * The comparison is used by the intrinsic C functions
  * qsort and bsearch, and it differs from the the comparison in
  * function cmpstia2() because it compares all of the iffxyn, ifval,
  * iffxynd and ifvald components of the structure, whereas
@@ -137,9 +131,7 @@ cmpstia1(const void *pe1, const void *pe2)
 /**
  * Define a comparison between two master Code/Flag table entries.
  *
- * This function defines a comparison between two entries within the
- * internal memory structure for storage of master Code/Flag table
- * entries.  The comparison is used by the intrinsic C function
+ * The comparison is used by the intrinsic C function
  * bsearch, and it differs from the the comparison in
  * function cmpstia1() because it only compares the iffxyn and ifval
  * components of the structure, whereas cmpstia1() compares all of
@@ -172,15 +164,12 @@ cmpstia2(const void *pe1, const void *pe2)
 /**
  * Store a new master Code/Flag table entry.
  *
- * This function adds a new entry to the internal memory structure for storage of
- * master Code/Flag table entries.
- *
- * @param ifxyn - Bit-wise representation of FXY number for which ival is a defined
+ * @param ifxyn - WMO bit-wise representation of FXY number for which ival is a defined
  * code or flag table entry.
  * @param ival  - Code figure or bit number.
  * @param meaning - Meaning associated with ifxyn and ival.
  * @param lmeaning - Length (in bytes) of meaning.
- * @param idfxy - Bit-wise representation of FXY number upon which ifxyn and ival
+ * @param idfxy - WMO bit-wise representation of FXY number upon which ifxyn and ival
  * depend (if any), or else set to a value of (-1).
  * @param idval - Code figure or bit number associated with idfxy and upon which ifxyn
  * and ival depend (if any), or else set to (-1) whenever idfxy is also set to (-1).
@@ -213,10 +202,7 @@ strtbfe(int ifxyn, int ival, char *meaning, int lmeaning, int idfxy, int idval)
 }
 
 /**
- * Sort entries within the master Code/Flag table.
- *
- * This function sorts the entries within the internal memory
- * structure for storage of master Code/Flag table entries, in
+ * Sort entries within the master Code/Flag table, in
  * preparation for future searches using function srchtbf().
  *
  * @author J. Ator @date 2017-11-16
@@ -231,10 +217,10 @@ sorttbf(void)
 /**
  * Search for a specified master Code/Flag table entry.
  *
- * This function searches for a specified FXY number and associated
+ * The search is based on a specified FXY number and associated
  * value (code figure or bit number) within the internal memory
- * structure for storage of master Code/Flag table entries, and if
- * found returns the associated meaning as a character string.
+ * structure for storage of master Code/Flag table entries.  If found,
+ * the associated meaning is returned as a character string.
  *
  * The search may optionally include a specified second FXY number
  * and associated value upon which the first FXY number and its
@@ -243,17 +229,17 @@ sorttbf(void)
  * originating center for which the sub-center in question is a
  * member.
  *
- * @param ifxyi - Bit-wise representation of FXY number to search for.
+ * @param ifxyi - WMO bit-wise representation of FXY number to search for.
  * @param ivali - Value (code figure or bit number) associated with ifxyi.
  * @param ifxyd - Dependence indicator:
- * - On input, ifxyd[0] is set to the bit-wise representation of the FXY
+ * - On input, ifxyd[0] is set to the WMO bit-wise representation of the FXY
  * number upon which ifxyi and ivali depend, or else set to (-1) if ifxyi
  * and ivali do not depend on the value associated with any other FXY number.
  * - On output, if the initial search of the master Code/Flag table was
  * unsuccessful, <b>and</b> if ifxyd[0] and ivald were both set to (-1) on
  * input, <b>and</b> if a second search of the table determines that the
  * meaning of ifxyi and ivali indeed depends on one or more other FXY numbers,
- * then the bit-wise representations of those FXY numbers are returned within
+ * then the WMO bit-wise representations of those FXY numbers are returned within
  * the first iret elements of ifxyd.
  * @param ivald - Value (code figure or bit number) associated with the FXY
  * number in ifxyd[0]; set to (-1) whenever ifxyd[0] is also set to (-1).
@@ -269,7 +255,7 @@ sorttbf(void)
  * - -1 = Meaning not found.
  * - >0 = Meaning not found, <b>and</b> ifxyd[0] and ivald were both set to (-1)
  * on input, <b>and</b> the meaning of ifxyi and ivali depends on the the value
- * associated with one of the FXY numbers whose bit-wise representation is
+ * associated with one of the FXY numbers whose WMO bit-wise representation is
  * stored in the first iret elements of ifxyd.
  *
  * @author J. Ator  @date 2018-01-11