Improve code documentation for MPAS dynamical core

[kuanchihwang]

Tag name (required for release branches):

None

Originator(s):

kuanchihwang

Descriptions (include the issue title, and the keyword ['closes', 'fixes', 'resolves'] followed by the issue number):

Improve code documentation for MPAS dynamical core.

• Add license header to each module
• Add descriptions to each module
• Keep code comments up-to-date
• Add support for auto-generating API documentation by using Fortran Documenter (FORD)

Describe any changes made to the build system:

None

Describe any changes made to the namelist:

None

List any changes to the defaults for the input datasets (e.g., boundary datasets):

None

List all files eliminated and why:

None

List all files added and what they do:

• A src/dynamics/mpas/assets/ford-config.md
  • Add configuration file for Fortran Documenter (FORD)

List all existing files that have been modified, and describe the changes:

• M src/dynamics/mpas/driver/dyn_mpas_subdriver.F90
  • Add license header to each module
  • Add descriptions to each module
  • Improve code documentation
• M src/dynamics/mpas/dyn_comp.F90
  • Add license header to each module
  • Add descriptions to each module
  • Improve code documentation
• M src/dynamics/mpas/dyn_coupling.F90
  • Add license header to each module
  • Add descriptions to each module
  • Improve code documentation
• M src/dynamics/mpas/dyn_grid.F90
  • Add license header to each module
  • Add descriptions to each module
  • Improve code documentation
• M src/dynamics/mpas/stepon.F90
  • Add license header to each module
  • Add descriptions to each module

Regression tests:

This is a documentation-only PR. No changes are expected to any existing tests.

[kuanchihwang]

Note to reviewers:

A preview of the generated documentation can be seen here.

This PR not only enables documentation generation by using Fortran Documenter (FORD), but also benefits the users of code editors with Fortran Language Server (FortLS) integration. Even if we do not use those features universally, the updated code comments are still helpful and look nice as-is.

[mgduda]

Have we received specific guidance on who holds the copyright? If I recall correctly, in the past we had been advised that the copyright should be assigned to the University Corporation for Atmospheric Research.

[kuanchihwang]

The license header is mentioned in #338. Perhaps @nusbaume could give us an updated guidance on this.

[kuanchihwang]

@mgduda @nusbaume With the guidance from the general counsel, I have changed the license header as in c228f35.

[nusbaume]

Thanks for the code comment and documentation updates @kuanchihwang!