Set up doxygen build and start using doxygen?

[edwardhartnett]

@webisu you mentioned an interest in doxygen?

We have used doxygen successfully with all the NCEPLIBS and we've worked out a good, easy way to do it. Do you want me to outfit the build with doxygen capability so you can experiment with it?

We can later take it out if you don't want to keep it.

However, I highly recommend doxygen as producing very professional-looking documentation with absolutely minimal programmer effort.

[webisu]

Wgrib2 routines are divided into 2 categories, core and options (f_). The majority of the code are options, and options have a calling interface that was designed for plug-n-play Note: the following lines are not formatted correctly /

• HEADER:100:bin:output:1:write binary data to X */

int f_bin(ARG1) {

100: -help sort order bin: option name output: type of option 1: number of arguments write....X description of the options (used by -help) fbin: f* signifies that this routine is an option ARG1 .. macro

The programmer is suppose to use ARG1 rather than the real API so that changes can be made to the API. I doubt that doxygen can handle this level of abstraction. ARG1 and ARG2 expose different amounts of information for the same API.

[edwardhartnett]

Pretty sure that doxygen could handle that with a little tweaking.

Does ARG1 and ARG2 remain constant for the whole build? That is, it's always the same?

Doxygen can handle pre-processor symbol substitution. So I think that would work.

[edwardhartnett]

I guess we decided not to use doxygen at this time.

[edwardhartnett]

Now that we know this code is going to remain with the NCEPLIBS team, we need to resolve the documentation problems. What would be best is if we could convert to doxygen, and do as all the other NCEPLIBS repos do. Doxygen is simple, capable, and produces very nice documentation with a minimum of programmer effort.

Some documentation requirements:

• Versioned releases of documentation.
• Every function/subroutine fully documented.
• Documentation is with the code.
• Attractive HTML output easy to generate.

Doxygen allows us to meet these requirements and is being used in all other EMC software.