search

NOAA-EMC / NCEPLIBS-bufr

The NCEPLIBS-bufr library contains routines and utilites for working with the WMO BUFR format.
Other
44 stars 19 forks source link

improve documentation #397

Closed edwardhartnett closed 11 months ago

edwardhartnett commented 1 year ago

As a result of the testing campaign we are currently undertaking, there will be a lot of documentation improvements.

edwardhartnett commented 1 year ago

When we look at the built documentation, we see a lot of lists of things, and their brief descriptions. For example:

image

The problem here is all the wasted space saying: "This module contains ".

To combat this, we will adopt an oft-used doxygen convention, which is to write our brief descriptions as if those words were already present. So instead of:

!> This module declares and initializes the MAXMEM variable. we write:

!> Declare and initialize the MAXMEM variable.

This applies to subroutines/functions as well, where we need to change from:

C> This function calls BUFRLIB subroutine readmm() and passes
C> back its return code as the function value.

to:

C> Calls BUFRLIB subroutine readmm() and pass
C> back its return code as the function value.

I will start changing this in every documentation I touch in testing, others should do the same. Remember that the brief description is supposed to be brief. So I would further edit the above to:

C> Call readmm() and returns its return code.
edwardhartnett commented 1 year ago

What exactly do we mean by:

"bit-wise representation of FXY number"?

Isn't this just the same as "number"? That is, every number on the computer is a bit-wise representation of a number. I see from the documentation of ifxy,f:

C> @remarks C> Per the [official WMO BUFR regulations](@ref manual), an FXY value C> can be represented as a bit-wise integer in 16 bits, ordered from C> left (most significant) to right (least significant), and where the C> F value occupies the first 2 bits, the X value occupies the next 6 C> bits, and the Y value occupies the last 8 bits. C> C> For example, if ADSC = '063022' C> C> F | X | Y C> 0 | 63 | 22 C> 0 0 1 1 1 1 1 1 0 0 0 1 0 1 1 0 C> C> then the corresponding ifxy C> C> = ( 213 + 212 + 211 + 210 + 29 + 28 + C> 24 + 22 + 2**1 ) C> C> = 16150

So this makes it a little more clear. This is a WMO thing. So perhaps we should be calling it a "WMO bit-wise representation of FXY number"?

edwardhartnett commented 1 year ago

Or maybe "WMO packed representation of FXY number?"

edwardhartnett commented 1 year ago

Somehow our module list is getting tangled up with the entries in the release notes:

image