search

NOAA-EMC / WW3

WAVEWATCH III
Other
265 stars 542 forks source link

Add doxygen marked-down source #586

Open MatthewMasarik-NOAA opened 2 years ago

MatthewMasarik-NOAA commented 2 years ago

Add Doxygen Documentation

For each file, document each contained Fortran code units (file, module, subroutine, etc.) using the agreed upon doxygen headers:

MatthewMasarik-NOAA commented 2 years ago

I can't edit your PR description, but I can now raise a PR against your repo (although I have not done so yet), so it does fix that issue.

Okay, that is good news you can raise a PR now.

If you can update the description with my name against those files I will raise a PR when I am done. Thanks!

sure thing! I've got those assigned to you.

MatthewMasarik-NOAA commented 1 year ago

Hi @aronroland @MathieuDutSik, do either of you have interest in adding doxygen documentation to the .F90 files in PDLIB? I see there is already some snippets added. It would be really great to have the original authors who are most familiar with the code to be involved. No pressure though, I wanted to offer to you first since you wrote it. Thanks

aronroland commented 1 year ago

Hi Mathew, yes definitely this must be done, we started it long time ago but it was laid down. I will do that asap. Thanks for looking at this!

MatthewMasarik-NOAA commented 1 year ago

Hi Aron, that's great news! Thank you.

MatthewMasarik-NOAA commented 1 year ago

💯

edwardhartnett commented 10 months ago

@MatthewMasarik-NOAA and I discussed this doxygenation effort as part of the larger EMC documentation effort.

Excellent documentation is a requirement for all EMC science codes. Good documentation speeds development, prevents bugs, and greatly assists testing efforts, especially when tests are being written by those who did not originate the code. Good documentation is all that stands between a programmer and the misuse of his or her code, causing an expensive or embarrassing problem which could easily have been avoided.

We have upgraded the documentation to doxygen, with high standards, on all the NCEPLIBS, UFS_UTILS, UPP, and soon fv3atm. It's great to see it happening on WW3 and we are ready to help out, as we did with the other projects.

The ultimate goal, which takes effort, but is well worth it, is to turn on doxygen checking in the CI system.

Currently, for NCEPLIBS or UFS_UTILS, if a contributor submits a PR with undocumented code, it will fail CI. This provides immediate feedback to the programmer and allows them to resolve the problem cheaply and immediately. They can submit a PR at 3 am, notice it failed, and have the documentation updated by 3:15 am. All without involving Matt or any other team member.

This is how other science software projects maintain excellent documentation with very few programmers. We automate as much as we can, to save team time to work on important programming problems.