Add doxygen documentation

[edwardhartnett]

As described here:
NOAA-EMC/NCEPLIBS#121

[edwardhartnett]

@jbathegit what is the sate of documentation for this code? I'm looking around and do see anything obvious...

[jbathegit]

Sorry, I don't have any experience with doxygen, and I also don't have time to learn it right now. That said, there are already docblocks inside all of the BUFRLIB subprograms, and there's also an online user guide at https://emc.ncep.noaa.gov/emc/pages/infrastructure/bufrlib.php

That's pretty-much all of the BUFRLIB documentation we have at this point, but feel free to take that and run with it if you like.

[jbathegit]

Also, where did "Version 11.5.0" come from? The next release version of BUFRLIB should be 11.4.0, unless I missed something(?)

[edwardhartnett]

You have a release 11.4.0, so 11.5.0 seems next. ;-)

Who maintains the documentation here: https://emc.ncep.noaa.gov/emc/pages/infrastructure/bufrlib.php

Where is the source for this documentation?

Thanks!

[jbathegit]

OK, clearly I've been a bit out of the loop, as 11.3.2 was the last release I was aware of. But that's fine and no worries, and I appreciate all of the expertise and help from you and others to modernize the support and usefulness of this library for a wider audience. My own particular area of knowledge centers around the legacy contents of the src and test subdirectories, mainly to support the WCOSS user community over the past many years. But I realize we're collectively working towards a more modernized approach for all of the NCEP libraries using CMake, Doxygen and other tools, and I'm happy to support that wherever I can.

As for the web pages, I've been maintaining those pretty-much on my own for many years. The latest source code is on the emcrzdm server, under the top-level directory /home/www/emc/htdocs/emc/pages/infrastructure/bufrlib/

[edwardhartnett]

We are going to standardize on doxygen for all NCEPLIBS. We need to copy any useful info from the web pages to the doxygen docs. You can then continue to maintain the web pages if you wish, retire them, or add a link to the on-line doxygen docs. Whenever you add info to the web pages, make sure to add that to the doxygen docs as well.

For an example of what this might look like with NCEPLIBS, see the NCEPLIBS-sp project, which is pretty far along in doxygen conversion. https://noaa-emc.github.io/NCEPLIBS-sp/

The old ways of doing things have taken us far, and given us this valuable legacy software. It's our role to now move that forward to 21st Century methods of software development, including more testing, increased continuous integration, better documentation, and more portable builds. In this way, NOAA and the science community can continue to receive benefit from this important software.

The NCEPLIBS team will benefit from doxygen in the following ways:

• Gives the user a consistent look and feel across all NCEPLIBS documentation.
• Provides modern documentation capabilities, like auto hyper-links, ability to include diagrams and images.
• Retains full control of web css and other style choices.
• Provides a standard approach to documentation for all team programmers.
• Takes full advantage of github features to maintain and display project documentation for free on project io site.
• Allows automatic checking of documentation in new code submissions.
• Well-known, so outside software contributors will find it easy to provide documentation with their changes.

Learning doxygen is easy, and can be done mostly from example. There are times when you may wish to google a question, but doxygen is the leading documentation tool in the free software world, and the answers are out there.

As we convert to doxygen, code changes that don't support the doxygen documentation should not be merged. In other words, we cannot let anyone break or neglect the docs moving forward. Every function must be properly documented, and we will check that in the CI and in code review.

[jbathegit]

So someone (me?) needs to go through 300+ subprograms to add in author, file, param, date, etc. tags inside of each one and then figure out how to get doxygen to display everything properly? Do we have any NCEPLIBS resources to help with this, or is the expectation that I'm going to be the one to do this?

If this is going to fall on me, then so be it, but I can't promise how quickly I'd be able to get this done. Again, I have no experience with doxygen at this point, and at least based on a quick look at the NCEPLIBS-sp example, I'm not even sure it will adequately replicate all of the functionality of the user guide, so I may end up needing to maintain both sites going forward anyway. Hopefully not, but I guess we'll see...

[jbathegit]

Or do we only need to put doxygen tags in the user-callable subprograms of the library, and not in all of the lower-level routines that are never intended to be called directly from an application program? That would make the task much more manageable.

[edwardhartnett]

As always we will proceed in an incremental fashion towards the ideal and stop when the benefits seem lower than the costs. That's agile programming. ;-)

Yes, we have resources to help! We are a team and will resolve these issues as a team, which means some will be experts in doxygen and get things spun up everywhere, and others will just be expected to keep things working, and document new and changed code.

My immediate goal is to get all the NCEPLIBS existing documentation converted to doxygen, and then we can all require that new and changed code be properly documented so as not to break it.

Ideally, even internally functions are documented, and as a programmer, I always will write documentation for any undocumented function before I change a line of code in that function. But whether this repo ever gets to that level of documentation is an open question. In this issue, we are just saying the existing docs will be converted to doxygen, and it will become the documentation format for this repo moving forward.

[edwardhartnett]

To answer your more specific question, the library has a publicly callable API. It's reasonable for the user to expect documentation for all those functions.