Update docs for modules and files

File and Module Docs

One requirement from my side for the documentation would be to at least provide short descriptions for:

• modules: https://chs.pages.ufz.de/forces/latest/namespaces.html
• files: https://chs.pages.ufz.de/forces/latest/files.html

One good example is given in mo_cli.f90:

!> \file    mo_cli.f90
!> \brief   \copybrief mo_cli
!> \details \copydetails mo_cli

!> \brief   Module to parse command line arguments.
!> \version 0.1
!> \authors Sebastian Mueller
!> \date    May 2021
!> \details A simple parser for command line arguments.
!!          You can define options and then parse the given command.
!!          Option can be with or without passed values and they can be set
!!          as required.
!!
!!          The following example demonstrates the functionality:
!!          \code{.f90}
!!          program main
!!            use mo_cli, only: cli_parser
!!            ...
!!          \endcode
module mo_cli

Function Docs

Alot of functions have doc-strings that are incompatible with Doxygen.

These should simply look like this:

  !> \brief Create a new \ref cli_parser.
  !> \return The new \ref cli_parser.
  type(cli_parser) function new_cli_parser(prog, description, add_help_option, add_version_option, version)
    use mo_os, only: path_split
    implicit none
    character(*), optional, intent(in) :: prog !< Program name (default will be arg(0))
    character(*), optional, intent(in) :: description !< help text for the cli
    logical, optional, intent(in) :: add_help_option !< whether to add a help option (--help, -h)
    logical, optional, intent(in) :: add_version_option !< whether to add a version option (--version, -v)
    character(*), optional, intent(in) :: version !< Program version

We don't have to separately document the input type since doxygen does that automatically.

Have a look at the doxygen identifiers: https://www.doxygen.nl/manual/commands.html

We only need \brief and maybe \details for subroutines and functions. Functions should also define a \return (see above).

We need a solution to document Interfaces where multiple subroutines are overloaded. Maybe this could help: https://stackoverflow.com/a/69620120/6696397