Merge branch 'develop' into ejh_yet_more_borts

src/rdmgsb.f

@@ -1,14 +1,16 @@
 C> @file
-C> @brief Read a specified data subset from a BUFR file
+C> @brief Read a specified data subset from a BUFR file.
 C>
 C> @author J. Woollen @date 2003-11-04
 
-C> This subroutine provides a handy way to combine the functionality
-C> of subroutines openbf(), readmg(), and readsb() within a single
-C> subroutine call.
+C> Read a specified data subset from a BUFR file.
+C>
+C> This subroutine combines the functionality of openbf(), 
+C> readmg(), and readsb().
 C>
 C> Logical unit LUNIT should not have already been opened via a
-C> previous call to subroutine openbf()
+C> previous call to subroutine openbf(). This subroutine will 
+C> open the file for input.
 C>
 C> Whenever this subroutine returns successfully, this indicates
 C> that a new data subset was successfully read into internal arrays

src/ufbcup.f

@@ -3,12 +3,26 @@
 C>
 C> @author Woollen @date 1994-01-06
 
-C> This subroutine makes one copy of each unique element in an
-C> input subset buffer into the identical mnemonic slot in the output
-C> subset buffer.
+C> Copy unique elements of a data subset.
 C>
-C> @param[in] LUBIN - integer: fortran logical unit number for input BUFR file.
-C> @param[in] LUBOT - integer: fortran logical unit number for output BUFR file.
+C> This subroutine makes one copy of each unique element in an input
+C> subset buffer into the identical mnemonic slot in the output subset
+C> buffer.
+C>
+C> Before this subroutine is called:
+C> - The input file must be opened for input with openbf().
+C> - a message must be read, as with readmg().
+C> - a subset of data loaded into memory, as with readsb().
+C> - the output file must be opened for output with openbf().
+C> - a message must be created in the output file, as with openmg().
+C>
+C> After this subroutine is called, writsb() must be called on the output
+C> file to write the subset to file.
+C>
+C> @param[in] LUBIN - integer: fortran logical unit number for input BUFR
+C> file.
+C> @param[in] LUBOT - integer: fortran logical unit number for output
+C> BUFR file.
 C>
 C> @author Woollen @date 1994-01-06
       RECURSIVE SUBROUTINE UFBCUP(LUBIN,LUBOT)

src/ufbint.f

@@ -7,7 +7,7 @@
 C>
 C> This subroutine reads or writes one or more data values from or to
 C> the BUFR data subset that is currently open within the BUFRLIB
-C> internal arrays.  The direction of the data transfer is determined
+C> internal arrays. The direction of the data transfer is determined
 C> by the context of ABS(LUNIN):
 C> - If ABS(LUNIN) points to a file that was previously opened for
 C>   input using subroutine openbf(), then data values are read from
@@ -18,24 +18,24 @@
 C>
 C> This subroutine is specifically designed for use with Table B
 C> mnemonics which are part of a delayed-replication sequence, or for
-C> which there is no replication at all.  See also subroutines ufbrep(),
+C> which there is no replication at all. See also subroutines ufbrep(),
 C> ufbseq() and ufbstp(), which can also be used to read/write one or
 C> more data values from/to a data subset but are designed for
-C> different use cases.  A more detailed discussion of
+C> different use cases. A more detailed discussion of
 C> these different use cases, including examples, is available in
 C> [DX BUFR Tables](@ref ufbsubs).
 C>
 C> It is the user's responsibility to ensure that USR is dimensioned
 C> sufficiently large enough to accommodate the number of data values
-C> that are to be read from or written to the data subset.  Note also
+C> that are to be read from or written to the data subset. Note also
 C> that USR is an array of real*8 values; therefore, any data that are
 C> to be written out as character (i.e. CCITT IA5) values in
 C> BUFR must be converted from character into real*8 format within the
-C> application program before calling this subroutine.  Conversely,
+C> application program before calling this subroutine. Conversely,
 C> when this subroutine is being used to read character values from a
 C> data subset, the value that is returned will be in real*8 format
 C> and must be converted back into character format by the application
-C> program before it can be used as such.  Alternatively, there are
+C> program before it can be used as such. Alternatively, there are
 C> different subroutines such as readlc() and writlc() which can be
 C> used to read/write character data directly from/to a data subset
 C> without the need to convert from/to real*8 format as an intermediate
@@ -44,7 +44,7 @@
 C> Numeric (i.e. non-character) data values within USR are always in
 C> the exact units specified for the corresponding mnemonic within the
 C> relevant DX or master BUFR table, without any scale or reference
-C> values applied.  Specifically, this means that, when writing
+C> values applied. Specifically, this means that, when writing
 C> data values into an output subset, the user only needs to store each
 C> respective value into USR using the units specified within the table,
 C> and the BUFRLIB software will take care of any necessary scaling or
@@ -55,16 +55,16 @@
 C> corresponding mnemonics within the table.
 C>
 C> "Missing" values in USR are always denoted by a unique
-C> placeholder value.  This placeholder value is initially set
+C> placeholder value. This placeholder value is initially set
 C> to a default value of 10E10_8, but it can be reset to
 C> any substitute value of the user's choice via a separate
-C> call to subroutine setbmiss().  In any case, and whenever this
+C> call to subroutine setbmiss(). In any case, and whenever this
 C> subroutine is used to read data values from an input subset, any
 C> returned value in USR can be easily checked for equivalence to the
 C> current placeholder value via a call to function ibfms(), and a
 C> positive result means that the value for the corresponding mnemonic
 C> was encoded as "missing" in BUFR (i.e. all bits set to 1) within the
-C> original data subset.  Conversely, whenever this subroutine
+C> original data subset. Conversely, whenever this subroutine
 C> is used to write data values to an output subset, the current
 C> placeholder value can be obtained via a separate call to function
 C> getbmiss(), and the resulting value can then be stored into the
@@ -76,7 +76,7 @@
 C> - If LUNIN < 0, and if ABS(LUNIN) points to a file that is open
 C> for output (writing BUFR), then the subroutine will treat the file
 C> pointed to by ABS(LUNIN) as though it was open for input (reading
-C> BUFR).  This is a special capability for use by some applications
+C> BUFR). This is a special capability for use by some applications
 C> that need to read certain values back out from a BUFR file during
 C> the same time that it is in the process of being written to.
 C> - If ABS(LUNIN) points to a file that is open for input (reading
@@ -85,15 +85,15 @@
 C> replication indicators {} or (), respectively, within the
 C> assocated DX BUFR table), and the corresponding location in USR
 C> will contain the total number of replications of that mnemonic
-C> within the data subset.  Note that, when using this option, the
+C> within the data subset. Note that, when using this option, the
 C> applicable replication indicators must be included in STR
 C> along with the mnemonic itself, as shown in an example in the
 C> discussion of [DX BUFR Tables](@ref ufbsubs).
 C> - If ABS(LUNIN) points to a file that is open for input (reading
 C> BUFR), there are a few additional special mnemonics that can be
 C> included within STR when calling this subroutine, and which in turn
 C> will result in special information being returned within the
-C> corresponding location in USR.  These special mnemonics are not
+C> corresponding location in USR. These special mnemonics are not
 C> considered to be part of Table B or Table D and therefore do not
 C> need to be definied within the DX or master table file associated
 C> with ABS(LUNIN):
@@ -106,35 +106,30 @@
 C>               the BUFR message pointed to by IREC, counting from
 C>               the beginning of the message
 C>
-C> @param[in] LUNIN   -- integer: Absolute value is Fortran logical
-C>                       unit number for BUFR file
-C> @param[in,out] USR -- real*8(*,*): Data values
-C>                         - If ABS(LUNIN) was opened for input, then
-C>                           USR is output from this subroutine and
-C>                           contains data values that were read
-C>                           from the current data subset.
-C>                         - If ABS(LUNIN) was opened for output, then
-C>                           USR is input to this subroutine and
-C>                           contains data values that are to be
-C>                           written to the current data subset.
-C> @param[in] I1 -- integer: First dimension of USR as allocated
-C>                  within the calling program
-C> @param[in] I2 -- integer:
-C>                    - If ABS(LUNIN) was opened for input, then I2
-C>                      must be set equal to the second dimension
-C>                      of USR as allocated within the calling program
-C>                    - If ABS(LUNIN) was opened for output, then I2
-C>                      must be set equal to the number of replications
-C>                      of STR that are to be written to the data subset
-C> @param[out] IRET -- integer: Number of replications of STR that were
-C>                     read/written from/to the data subset
-C> @param[in] STR -- character*(*): String of blank-separated
-C>                   Table B mnemonics
-C>                   in one-to-one correspondence with the number of data
-C>                   values that will be read/written from/to the data
-C>                   subset within the first dimension of USR (see
-C>                   [DX BUFR Tables](@ref dfbftab) for further
-C>                   information about Table B mnemonics)
+C> @param[in] LUNIN - integer: Absolute value is Fortran logical
+C> unit number for BUFR file.
+C> @param[in,out] USR - real*8(*,*): Data values
+C>  - If ABS(LUNIN) was opened for input, then USR is output from this subroutine and
+C>    contains data values that were read from the current data subset.
+C>  - If ABS(LUNIN) was opened for output, then USR is input to this subroutine and
+C>    contains data values that are to be written to the current data subset.
+C> @param[in] I1 - integer: First dimension of USR as allocated
+C> within the calling program.
+C> @param[in] I2 - integer:
+C>  - If ABS(LUNIN) was opened for input, then I2
+C>    must be set equal to the second dimension
+C>    of USR as allocated within the calling program
+C>  - If ABS(LUNIN) was opened for output, then I2
+C>    must be set equal to the number of replications
+C>    of STR that are to be written to the data subset
+C> @param[out] IRET - integer: Number of replications of STR that were
+C> read/written from/to the data subset
+C> @param[in] STR - character*(*): String of blank-separated
+C> Table B mnemonics in one-to-one correspondence with the number of data
+C> values that will be read/written from/to the data
+C> subset within the first dimension of USR (see
+C> [DX BUFR Tables](@ref dfbftab) for further
+C> information about Table B mnemonics)
 C>
 C> @author J. Woollen @date 1994-01-06