Suggest we move F77 documentation into fortran code

[edwardhartnett]

I have been working a lot with doxygen and fortran on the PIO project. Although there are some gotchas, it's possible to have documenation with the code, and get the usual benefits of doxygen, including automatic linking to function names, etc.

What I suggest is that I do this for the F77 API documentation. This will require changes to the Doxyfile.in as well, so that doxygen looks at the fortran code files, instead of the .md files.

Keeping the documentation with the code is a proven technique for improving accuracy and clarity. Doxygen has some challenges dealing with Fortran, so expectations must be tempered - not every fancy feature may be available. But I can reproduce the layout of the current F77 API documentation.

@WardF does this sound like a good plan to you?

[WardF]

I think that would be great

[edwardhartnett]

OK, some good news on this front. I have recently been engaged in an effort to bring much better documentation to some NOAA libraries. As a result, we have explored using doxygen with F77 and F90 quite a bit. There are some tricks and traps.

More good news is that recent doxygen versions (since 1.8.5) have included much better support for Fortran, including F90 constructs like modules.

So I can confirm that although it didn't work particularly well in the past, doxygen + fortran works very well now. All I need is the time to do this task. ;-)

[edwardhartnett]

Well documentation tasks got their usual level of priority in a programmer's life, and I have not even attempted this yet.

I will try to take a look at this after the next netcdf-fortran release, and meanwhile just focus on the existing documentation.