modernize C-Fortran interface for cread functions

[jbathegit]

Fixes #421

Part of #79 Part of #254

[jbathegit]

Hmm, so this is failing in Doxygen in the developer CI. It took me a while to find it, but the applicable message is:

Generating docs for namespace bufrlib
Generating docs for compound bufrlib::backbufr_c...
Exiting...
make[2]: *** [docs/CMakeFiles/doc.dir/build.make:71: docs/CMakeFiles/doc] Error 1
make[1]: *** [CMakeFiles/Makefile2:2377: docs/CMakeFiles/doc.dir/all] Error 2

which is an interface defined in the new bufrlib.F90 module. I tried to model this on the earlier code in bufr_interface.F90 where Doxygen was being squawky about the @fn notation, and (I think) the only difference here is that this module name is bufrlib instead of bufr_interface, but I seem to be missing something else. @edwardhartnett, any thoughts?

[jbathegit]

In the meantime, could you please help me figure out why Doxygen is squawking in the developer CI build? ;-) That was my original problem, and I can't reproduce it with the older version of Doxygen on my local machine. I honestly don't understand what it's complaining about.

[edwardhartnett]

Yes I will take a look at doxygen. Stand by...

[edwardhartnett]

How come you can't run doxygen?

Generating docs for compound bufrlib::backbufr_c...
/home/ed/NCEPLIBS-bufr/src/bufrlib.F90:57: warning: parameters of member bufrlib::backbufr_c::backbufr_c are not (all) documented
Generating docs for compound bufrlib::cewind_c...
/home/ed/NCEPLIBS-bufr/src/bufrlib.F90:68: warning: parameters of member bufrlib::cewind_c::cewind_c are not (all) documented
Generating docs for compound bufrlib::closfb_c...
/home/ed/NCEPLIBS-bufr/src/bufrlib.F90:79: warning: parameters of member bufrlib::closfb_c::closfb_c are not (all) documented
Generating docs for compound bufrlib::crdbufr_c...
/home/ed/NCEPLIBS-bufr/src/bufrlib.F90:90: warning: parameters of member bufrlib::crdbufr_c::crdbufr_c are not (all) documented
Generating docs for compound bufrlib::cwrbufr_c...
/home/ed/NCEPLIBS-bufr/src/bufrlib.F90:102: warning: parameters of member bufrlib::cwrbufr_c::cwrbufr_c are not (all) documented
Generating docs for compound bufrlib::openab_c...
/home/ed/NCEPLIBS-bufr/src/bufrlib.F90:45: warning: parameters of member bufrlib::openab_c::openab_c are not (all) documented
Generating docs for compound bufrlib::openrb_c...
/home/ed/NCEPLIBS-bufr/src/bufrlib.F90:21: warning: parameters of member bufrlib::openrb_c::openrb_c are not (all) documented
Generating docs for compound bufrlib::openwb_c...
/home/ed/NCEPLIBS-bufr/src/bufrlib.F90:33: warning: parameters of member bufrlib::openwb_c::openwb_c are not (all) documented

[edwardhartnett]

OK, I did a commit to this branch which turns off parallel builds in developer.yml.

I changed this:

make -j2 VERBOSE=1 to:

make VERBOSE=1

Now we can clearly see the first doxyen error in the output:

/home/runner/work/NCEPLIBS-bufr/NCEPLIBS-bufr/bufr/src/bufrlib.F90:57: error: parameters of member bufrlib::backbufr_c::backbufr_c are not (all) documented (warning treated as error, aborting now)

Since WARN_AS_ERROR is YES, in docs/Doxyfile.in, the build will break at the first documentation error. If you temporarily turn off WARN_AS_ERROR in your branch, the documentation build will succeed and you will see all the warnings. I will demonstrate...

[edwardhartnett]

OK, I turned off WARN_AS_ERROR in the Doxyfile.in. Now the developer workflow completes. Since I've also turned off parallel builds, it's easy to find all the doxygen warnings in the output:

/home/runner/work/NCEPLIBS-bufr/NCEPLIBS-bufr/bufr/src/bufrlib.F90:57: warning: parameters of member bufrlib::backbufr_c::backbufr_c are not (all) documented
/home/runner/work/NCEPLIBS-bufr/NCEPLIBS-bufr/bufr/src/bufrlib.F90:68: warning: parameters of member bufrlib::cewind_c::cewind_c are not (all) documented
/home/runner/work/NCEPLIBS-bufr/NCEPLIBS-bufr/bufr/src/bufrlib.F90:79: warning: parameters of member bufrlib::closfb_c::closfb_c are not (all) documented
/home/runner/work/NCEPLIBS-bufr/NCEPLIBS-bufr/bufr/src/bufrlib.F90:90: warning: parameters of member bufrlib::crdbufr_c::crdbufr_c are not (all) documented
/home/runner/work/NCEPLIBS-bufr/NCEPLIBS-bufr/bufr/src/bufrlib.F90:102: warning: parameters of member bufrlib::cwrbufr_c::cwrbufr_c are not (all) documented
/home/runner/work/NCEPLIBS-bufr/NCEPLIBS-bufr/bufr/src/bufrlib.F90:45: warning: parameters of member bufrlib::openab_c::openab_c are not (all) documented
/home/runner/work/NCEPLIBS-bufr/NCEPLIBS-bufr/bufr/src/bufrlib.F90:21: warning: parameters of member bufrlib::openrb_c::openrb_c are not (all) documented
/home/runner/work/NCEPLIBS-bufr/NCEPLIBS-bufr/bufr/src/bufrlib.F90:33: warning: parameters of member bufrlib::openwb_c::openwb_c are not (all) documented

So this is a demonstration of how you can easily see your doxygen warnings in the CI system,

But that's not how I do things. Instead, I have installed doxygen-1.9.1 on my machine and set my PATH to find that version first. Then I can run make in the build/docs directory after running cmake, and I get a doxygen build. I find that a little easier than waiting for the CI.

But the CI will work as well, so if you can't install doxygen on your system (but why can't you?) then you can use the CI instead.

[edwardhartnett]

Well you have not defined the params for lots of the functions. For example:

    !> @fn bufrlib::backbufr_c::backbufr_c(nfile)
    !> Backspace a BUFR file by one BUFR message.
    !>
    !> Wraps backbufr() function.
    !>
    !> @author J. Ator @date 2005-11-29
    subroutine backbufr_c( nfile ) bind(C, name='backbufr')

Where's the @param nfile line in the documentation?

[edwardhartnett]

OK, I'm going to leave parallel builds off, and WARN_AS_ERROR off, in your branch. Once you fix your warnings, make sure you turn them on again.

[jbathegit]

ARGGH, I can't believe I missed that! Thanks for your help, and I'll get that fixed and pushed up.

As for why I can't install doxygen on my system, I'm working on WCOSS2, which has a strict rule about users installing their own 3rd-party libraries. The system does have doxygen already installed, but it's a much older version 1.8.14, and it wasn't showing any of the above output when I ran it myself with -DENABLE_DOCS=On. So thanks again for your help here!

[edwardhartnett]

OK, glad to help! Lot's of really great test improvements happening - it's encouraging to see. Last I checked, 82.4%. That number keeps climbing! ;-)

[jbathegit]

Thanks, and we should be good to go with this PR now. If you could please approve it then I'll get it merged. Or if you still have any concerns that I haven't addressed yet, please let me know.