more documentation, including for all modv files

docs/ReleaseNotes.md

@@ -44,6 +44,11 @@ more than one BUFR message could become available during such a call.
 compatibility with GNU v10+ compilers.
 [[Issue #81](https://github.com/NOAA-EMC/NCEPLIBS-bufr/issues/81)]
 
+* Subroutines pkx and chrtrn are no longer used within the library and were
+never intended to be called from application codes, so they have now been
+removed from the library.
+[[Issue #107](https://github.com/NOAA-EMC/NCEPLIBS-bufr/issues/107)]
+
 
 ### Version 11.3.2 - July 16, 2020
 

src/bufr_interface.f90

@@ -1,11 +1,11 @@
 !> @file
-!> @brief Enable a number of Fortran BUFRLIB functions to be called
-!>        from C and C++ application programs.
+!> @brief Enable a number of BUFRLIB subprograms to be called
+!>        via wrapper functions from C and C++ application programs.
 !>
 !> @author Ronald Mclaren
 !> @date 2020-07-29
 
-!> This module contains functions which map certain Fortran BUFRLIB
+!> This module contains functions which wrap certain Fortran BUFRLIB
 !> functions so they can be called from C and C++. The signatures of
 !> the public functions match their Fortran equivalents, as shown within
 !> the documentation for each of the individual functions.

src/bufr_interface.h

@@ -1,14 +1,14 @@
 /** @file
-    @brief Define signatures for C functions which wrap native Fortran
-    BUFRLIB functions. 
+    @brief Define signatures to enable a number of BUFRLIB 
+    subprograms to be called via wrapper functions from C and C++
+    application programs.
 
     @author Ronald Mclaren
     @date 2020-07-29
 
-    <p>This header file defines the C function signatures for the Fortran
-       functions exposed in bufr_interface.f90. It is intended for use by
-       C/C++ application programs that wish to call BUFRLIB functions
-       written in Fortran.
+    <p>This header file defines the signatures for the functions
+       in bufr_interface.f90 which wrap a number of native Fortran
+       subroutines in the BUFRLIB.
 */
 
 #pragma once

src/bufrlib.h.in

@@ -1,10 +1,13 @@
 /** @file
- *  @brief Define signatures for C functions which are native C
- *  BUFRLIB functions.
+ *  @brief Define signatures to enable a number of BUFRLIB
+ *  subprograms to be called directly from C application programs.
  *
- *  <p>This header file defines the C function signatures for all
- *  BUFRLIB functions written in C.  It also contains other macros
- *  used throughout the C portion of the library.
+ *  <p>This header file defines the signatures for all
+ *  BUFRLIB subprograms which are native C functions, or which are
+ *  native Fortran subroutines but can be called directly from C
+ *  application programs without the use of wrapper functions.
+ *  This header file also contains macros used throughout the C
+ *  portion of the BUFRLIB.
  *
  *  @author J.Ator
  *  @date 2003-11-04

src/cfe.h

@@ -1,24 +1,52 @@
-/** @file */
 /** @file
+ *  @brief Declare variables for internal storage of master Code/Flag
+ *  table entries.
+ */
+
+/**
+ *  This header file contains the structure and variable declarations
+ *  used to store master Code/Flag table entries internally.
+ *
+ *  @author J. Ator
+ *  @date 2017-11-16
  */
 
 #define MAX_MEANING_LEN 150
 
 struct code_flag_entry {
     f77int iffxyn;
-	/* Bitwise representation of FXY number to which this entry belongs. */
+    /** @var iffxyn
+     *  Bitwise representation of FXY number to which this entry belongs.
+     */
     f77int ifval;
-	/* Code figure or bit number. */
+    /** @var ifval
+     *  Code figure or bit number.
+     */
     char ifmeaning[MAX_MEANING_LEN+1];
-	/* Meaning corresponding to ifval. */
+    /** @var ifmeaning
+     *  Meaning corresponding to ifval.
+     */
     f77int iffxynd;
-	/* Bitwise representation of FXY number upon which this entry is
-	   dependent, if any.  Set to (-1) if no dependency. */
+    /** @var iffxynd
+     *  Bitwise representation of FXY number upon which this entry is
+     *  dependent, if any.  Set to (-1) if no dependency.
+     */
     f77int ifvald;
-	/* Code figure or bit number upon which this entry is dependent,
-	   if any.  Set to (-1) if no dependency. */
+    /** @var ifvald
+     *  Code figure or bit number upon which this entry is dependent,
+     *  if any.  Set to (-1) if no dependency.
+     */
 };
 
+/** @var cfe
+ *  Master Code/Flag table entries.
+ *
+ *  @var mxmtbf
+ *  Maximum number of master Code/Flag table entries that can be stored.
+ *
+ *  @var nmtf
+ *  Number of stored master Code/Flag table entries in cfe.
+ */
 #ifdef IN_INITTBF
     struct code_flag_entry *cfe;  /* will automatically initialize to NULL */
     f77int mxmtbf;

src/moda_bitbuf.F

@@ -1,4 +1,11 @@
 C> @file
+C> @brief Declare arrays for internal storage of BUFR messages.
+
+C> This module contains array and variable declarations used to
+C> store BUFR messages internally for multiple I/O streams.
+C>
+C> @author J. Ator
+C> @date 2014-12-10
 
 	MODULE MODA_BITBUF
 
@@ -12,6 +19,16 @@ MODULE MODA_BITBUF
 	  USE MODV_NFILES
 #endif
 
+C>        @var maxbyt
+C>        Maximum length of an output BUFR message.
+C>
+C>        @var mbyt
+C>        Length (in bytes) of current BUFR message for each internal
+C>        I/O stream.
+C>
+C>        @var mbay
+C>        Current BUFR message for each internal I/O stream.
+
 	  INTEGER :: MAXBYT
 	  INTEGER :: IBIT
 #ifdef DYNAMIC_ALLOCATION

src/moda_bitmaps.F

@@ -1,4 +1,14 @@
 C> @file
+C> @brief Declare arrays for internal storage of bitmaps.
+
+C> This module contains array and variable declarations used to
+C> store bitmaps internally within a data subset definition.
+C>
+C> <p>Data values within this module are stored by subprograms
+C> strbtm(), igetrfel(), makestab() and tabsub().
+C>
+C> @author J. Ator
+C> @date 2016-05-27
 
 	MODULE MODA_BITMAPS
 
@@ -22,6 +32,64 @@ MODULE MODA_BITMAPS
 	  USE MODV_MXTAMC
 #endif
 
+C>        @var nbtm
+C>        Number of stored bitmaps for the current data subset
+C>        (up to a maximum of MXBTM).
+C>
+C>        @var nbtmse
+C>        Number of "set" entries (set to a value of 0)
+C>        in the bitmap.
+C>
+C>        @var linbtm
+C>        TRUE if a bitmap is in the process of being read for
+C>        the current data subset.
+C>
+C>        @var istbtm
+C>        Ordinal position in data subset definition corresponding
+C>        to the first entry of the bitmap.
+C>
+C>        @var iszbtm
+C>        Size of bitmap (total number of entries, whether
+C>        "set" (set to a value of 0) or not).
+C>
+C>        @var ibtmse
+C>        Ordinal positions in bitmap of bits that were "set" (set
+C>        to a value of 0); these ordinal positions can range in
+C>        value from 1 to iszbtm for each stored bitmap.
+C>
+C>        @var lstnod
+C>        Most recent jump/link table entry that was processed by
+C>        function igetrfel() and whose corresponding value type
+C>        was either numeric or CCITT IA5.
+C>
+C>        @var lstnodct
+C>        Current count of consecutive occurrences of lstnod.
+C>        
+C>        @var ntamc
+C>        Number of Table A mnemonics in jump/link table (up to a
+C>        maximum of MXTAMC) which contain at least one Table C
+C>        operator with an XX value of 21 or greater in their data
+C>        subset definition; only Table C operators with an XX
+C>        value of 21 or greater are tracked within this module,
+C>        since all others are automatically processed within
+C>        subroutines tabsub() and tabent().
+C>
+C>        @var inodtamc
+C>        Entries within jump/link table which contain Table A
+C>        mnemonics.
+C>
+C>        @var ntco
+C>        Number of Table C operators (with an XX value of 21 or
+C>        greater) within the data subset definition of the
+C>        corresponding Table A mnemonic in inodtamc.
+C>
+C>        @var ctco
+C>        Table C operators corresponding to inodtco.
+C>
+C>        @var inodtco
+C>        Entries within jump/link table which contain Table C
+C>        operators.
+
 	  INTEGER :: NBTM
 	  INTEGER :: NTAMC
 	  INTEGER :: LSTNOD

src/moda_nrv203.F

@@ -1,10 +1,63 @@
+C> @file
+C> @brief Declare arrays for internal storage of changed
+C> reference values.
+
+C> This module contains array and variable declarations for use
+C> with any 2-03-YYY (change reference value) operators present
+C> within the internal jump/link table.
+C>
+C> <p>Data values within this module are stored by subroutine
+C> tabsub().
+C>
+C> @author J. Ator
+C> @date 2012-03-02
+
 	MODULE MODA_NRV203
 
 #ifndef MXNRV_H
 #define MXNRV_H
 	  USE MODV_MXNRV
 #endif
 
+C>        @var nnrv
+C>        Number of entries in the jump/link table which contain
+C>        new reference values (up to a maximum of MXNRV).
+C>
+C>        @var ibtnrv
+C>        Number of bits in Section 4 occupied by each new
+C>        reference value for the current 2-03-YYY operator in
+C>        scope; set to 0 if no such operator is currently in
+C>        scope.
+C>
+C>        @var ipfnrv
+C>        A number between 1 and nnrv, denoting the first entry
+C>        within the module arrays which applies to the current
+C>        data subset in scope; set to 0 if no 2-03-YYY operators
+C>        have been applied to the current data subset in scope. 
+C>
+C>        @var tagnrv
+C>        Table B mnemonic to which the corresponding new
+C>        reference value in nrv applies.
+C>
+C>        @var nrv
+C>        New reference values corresponding to inodnrv.
+C>
+C>        @var inodnrv
+C>        Entries within jump/link table which contain new
+C>        reference values.
+C>
+C>        @var isnrv
+C>        Start of entry range in jump/link table, within which
+C>        the corresponding new reference value in nrv will be
+C>        applied to all occurrences of the corresponding
+C>        Table B mnemonic in tagnrv.
+C>
+C>        @var ienrv
+C>        End of entry range in jump/link table, within which
+C>        the corresponding new reference value in nrv will be
+C>        applied to all occurrences of the corresponding
+C>        Table B mnemonic in tagnrv.
+
 	  INTEGER :: NNRV
 	  INTEGER :: IBTNRV
 	  INTEGER :: IPFNRV

src/moda_tababd.F

@@ -1,3 +1,12 @@
+C> @file
+C> @brief Declare arrays for internal storage of DX BUFR tables.
+
+C> This module contains array and variable declarations used to
+C> store DX BUFR tables internally for multiple I/O streams.
+C>
+C> @author J. Ator
+C> @date 2014-12-10
+
 	MODULE MODA_TABABD
 
 #ifndef MAXTBA_H
@@ -20,6 +29,45 @@ MODULE MODA_TABABD
 	  USE MODV_NFILES
 #endif
 
+C>        @var ntba
+C>        Number of Table A entries for each internal I/O stream
+C>        (up to a maximum of MAXTBA, whose value is stored in
+C>        array element 0).
+C>
+C>        @var taba
+C>        Table A entries for each internal I/O stream.
+C>
+C>        @var idna
+C>        Message types (in array element 1) and subtypes (in array
+C>        element 2) corresponding to taba.
+C>
+C>        @var mtab
+C>        Entries within jump/link table corresponding to taba.
+C>
+C>        @var ntbb
+C>        Number of Table B entries for each internal I/O stream
+C>        (up to a maximum of MAXTBB, whose value is stored in
+C>        array element 0).
+C>
+C>        @var tabb
+C>        Table B entries for each internal I/O stream.
+C>
+C>        @var idnb
+C>        Bit-wise representations of the FXY values corresponding
+C>        to tabb.
+C>
+C>        @var ntbd
+C>        Number of Table D entries for each internal I/O stream
+C>        (up to a maximum of MAXTBD, whose value is stored in
+C>        array element 0).
+C>
+C>        @var tabd
+C>        Table D entries for each internal I/O stream.
+C>
+C>        @var idnd
+C>        Bit-wise representations of the FXY values corresponding
+C>        to tabd.
+
 #ifdef DYNAMIC_ALLOCATION
 	  INTEGER, ALLOCATABLE :: NTBA(:)
 	  INTEGER, ALLOCATABLE :: NTBB(:)