Improve documentation

[fmckeogh]

Currently, nearly all comments have been copied from the Fortran implementation. In most cases this is acceptable as the logic is the same so the comments are perfectly valid.

However, the doc comments could be improved by providing descriptions for each module and a top level summary of the project.

[olexandr-konovalov]

Does Rust have a proper documenting tool, BTW?

[fmckeogh]

Yes, cargo doc generates all documentation for a project (guide here). Currently CI is building and deploying documentation to https://rse-standrewscs.github.io/shallow-water/shallow_water/index.html, but once we have a stable release, we could have it on docs.rs.