documenting.F90

!*******************************************************************************

!> \page adding_documentation Documenting NMMB-MONARCH
!!
!! MONARCH uses <A HREF="http://www.doxygen.nl"> Doxygen </A>
!! to generate documentation directly from the model source code.
!! Larger documents, including some how-to's and general model descriptions, are
!! located in ``.F90`` files located in the \c DOC folder.
!! General usage and MONARCH style are described in the following sections.
!! More information can be found in the
!! <A HREF="http://www.doxygen.nl/manual/index.html"> Doxygen documentation
!! </A>.
!!
!! \section doc_general_usage General Documentation Style
!!
!! Placing a ``!>`` at the beginning of a
!! comment block and ``!!`` on lines 2+ of a comment block will signal Doxygen
!! to include these comments in the documentation.
!! Comments directly above a
!! function or subroutine can be used to document the purpose, usage and
!! science basis of the code.
!! Comments directly above a dummy variable can be
!! used to describe the variable.
!!
!! \subsection doc_general_formulas Formulas
!!
!! Math formulas can be included in \f$\LaTeX\f$ format between \c \\f$ and \c \\f$
!! flags for in-line formulas or <tt>\\f[</tt> and <tt>\\f]</tt> flags for separate formula
!! blocks.
!! For example, the following text:
!! \code{.f90}
!! !! here, \f$i \in 1...10\f$.
!! \endcode
!! is rendered as :
!!
!! here, \f$i \in 1...10\f$.
!!
!! \subsection doc_gen_markdown_html Markdown and HTML
!!
!! <A HREF="http://www.doxygen.nl/manual/markdown.html">Markdown</A> and
!! <A HREF="http://www.doxygen.nl/manual/htmlcmds.html">HTML commands</A>
!! can be included in the comments and will be rendered by Doxygen when
!! building the documentation.
!!
!! \subsection doc_gen_citations Citations
!!
!! Citations can be included using the \c \\cite flag followed by the name
!! of the citation as specified in \c DOC/references.bib. If a url is included
!! for the reference in the BibTeX file, it will be hyperlinked by Doxygen.
!!
!! \subsection doc_gen_example Example
!!
!! Here is an example of a function with Doxygen comments in standard
!! MONARCH style:
!! \code{.f90}
!! !> A brief description of my new function
!! !! More detailed information is included here, including a really
!! !! cool equation
!! !! \f[
!! !!   k = a e^{-k_B T}
!! !! \f]
!! !! and maybe a reference to published work \cite Me2018
!! function get_rate( pre_exp_factor__s, temperature__K )
!!
!!   !> Reaction rate [\f$s^{-1}\f$]
!!   real(kind=mflt) :: get_rate
!!   !> Pre-exponential factor [\f$s^{-1}\f$]
!!   real(kind=mflt), intent(in) :: pre_exp_factor__s
!!   !> Temperature [K]
!!   real(kind=mflt), intent(in) :: temperature__K
!!
!!   !...
!!
!! end function get_rate
!! \endcode
!!
!! \subsection doc_general_bugs_and_todos Bugs and Future Work
!!
!! The \c \\bug and \c \\todo flags can be used to document bugs in the code
!! and suggestions for improvements. The detailed function/subroutine
!! documentation will include \c bug and/or \c todo sections when these
!! flags are used. Additionally, Doxygen assembles a
!! \ref bug and a \ref todo from these flagged comments.
!!
!! Please be descriptive when using these flags. Avoid comments like
!! ``this is broken``.
!! When \c \\bug and \c \\todo flagged comments are assembled in a
!! list they are grouped by function/subroutine, but it may not be evident
!! what ``this`` refers to.
!!
!! Include your name and date for reference,
!! or if an issue in the MONARCH GitLab project has been created, include
!! a link to it. (Doxygen will generate a hyperlink when it finds a URL in
!! a comment block.)
!!
!! If the root cause of the bug is unknown,
!! try to describe the failure conditions:
!! \code{.f90}
!!   !> \bug Calculation of \f$C_i\f$ fails for \f$n>24\f$
!!   !! resulting in a seg. fault. using the \c REGIONAL_CHEM scenario.
!!   !! ( see issue:
!!   !!   https://earth.bsc.es/gitlab/ac/nmmb-monarch/issues/101 )
!!   do i = 1, n
!!     c(i) = a(i) + b(i)
!!   end do
!! \endcode
!!
!! \section doc_new_dev Documenting New Developments
!!
!! Developers of MONARCH are encouraged to follow suggestions given in
!! the MONARCH \ref coding_style "coding style guide".
!! The hope is that these suggestions will to lead to more modular (maybe even
!! <A HREF="https://gist.github.unparsedom/n-s-k/522f2669979ed6d0582b8e80cf6c95fd">object-oriented</A>!)
!! code.
!! In-code documentation is easier to use with functions and subroutines of
!! limited scope, rather than long blocks of serial code.
!! But, this style of coding is sometimes difficult to apply
!! when adding new features to existing code.
!! If your new development is being included in existing code that
!! follows a more tradtional FORTRAN style, see
!! \ref doc_existing_code for suggestions for in-code documentation.
!!
!! Regardless of the location and style of the new development, please
!! update the \ref what_is_monarch "scientific" and
!! \ref how_monarch_works "technical" descriptions of MONARCH to
!! describe the science and implementation of your work.
!!
!! If your development includes new configuration options, consider
!! updating (or creating) the corresponding
!! \ref config_formats "configuration file format" and
!! adding a \ref doc_how_tos "How To" to let MONARCH users know how to
!! make use of the new features.
!!
!!
!! \section doc_existing_code Documenting Existing Code
!!
!! MONARCH comprises a variety of modules, each with a particular coding
!! style and level of documentation.
!! Suggestions for working with existing code can be found
!! \ref coding_style "here".
!! Here are some suggestions for improving MONARCH documentation related
!! to existing code
!! (If you find a new way of improving the documentation of existing
!!  code, please share it here!):
!! - If you are working with a function or subroutine that is not yet
!!   preceded by a documentation block, add one that contains a short
!!   overview of the purpose and science basis of the function.
!!   In many cases, existing code contains large blocks of serial code
!!   for which a full description in a single comment block at the beginning
!!   would be large and difficult to maintain.
!!   For these cases, a short overview could be included in the
!!   main comment block:
!!   \code{.f90}
!!   !> Perform many tasks, all within a single subroutine
!!   !!
!!   !! Maybe include an overview of the procedure:
!!   !! - first do this
!!   !! - then this
!!   !! - finally, this
!!   subroutine do_everything( long, set, of, parameters )
!!
!!     !...
!!
!!   \endcode
!!   ... and descriptions of specific code blocks can be
!!   included within the function code. These will appear in the detailed
!!   description of the function in the generated documentation:
!!   \code{.f90}
!!     !> Perform some specific task
!!     !! Include an equation or two: \f$a + b = c\f$
!!     !! and a citation \cite SomeOne1962
!!     do i = 1, n
!!       c(i) = a(i) + b(i)
!!     end do
!!
!!     !...
!!
!!   end subroutine do_everything
!!   \endcode
!!
!! - Add descriptions of dummy variables (including units) when possible.
!!   It is not necessary to document every variable for a subroutine or
!!   function at once, just describe the ones you can. Several formats
!!   can be used that will result in the same generated documentation,
!!   including:
!!   \code{.f90}
!!   !> some parameter [units]
!!   real, intent(in) :: my_parameter
!!   \endcode
!!   and
!!   \code{.txt}
!!   real, intent(in) :: my_parameter !< some parameter [units]
!!   \endcode
!! - Add references when possible. Include the reference in the
!!   \c DOC/refrence.bib file in BibTeX format, and cite it in a
!!   documentation comment block using <tt>\\cite RefName2018</tt>.
!! - Review the \ref what_is_monarch "scientific" and
!!   \ref how_monarch_works "technical" descriptions of MONARCH and
!!   add missing or incomplete information.
!!
!! \section doc_how_tos How To's
!!
!! \ref how_tos "How-To's" can be included in the source code
!! (particularly when they apply to a specific MONARCH module) or
!! can be placed in separate files in the \c DOC/how_to folder.
!! In either case, they are structured as a single comment block
!! starting with a \c \\page flag, a label for referencing the
!! page from other parts of the documentation,
!! and the title of the How-To:
!! \code{.unparsed}
!!   !> \page how_to_calcot Cal&ccedil;otada
!! \endcode
!! Include a brief overview of the purpose and context of the How To:
!! \code{.unparsed}
!!   !! Cal&ccedil;otadas are {finish}
!! \endcode
!! Organize the document using the \c \\section and \c \\subsection
!! flags.
!! The labels placed after these flags can be used in other parts
!! of the document with the \c \\ref flag:
!! \code{.unparsed}
!!   !! \section calcot_planning Planning
!!   !!
!!   !! \subsection calcot_planning_timing Timing
!!   !!   Cal&ccedil;otadas are typically held in the late winter
!!   !!   or early spring.
!!   !!
!!   !! \subsection calcot_planning_location Location
!!   !!   Try to find an outdoor location with a place to make
!!   !!   a fire to cook the cal&ccedil;ots.
!!   !!
!!   !! \subsection calcot_planning_shopping Shopping List
!! \endcode
!! <A HREF="http://www.doxygen.nl/manual/markdown.html">Markdown commands</A>
!! can be useful when building lists:
!! \code{.unparsed}
!!   !!   -# Cal&ccedil;ots
!!   !!   -# Romesco sauce
!!   !!   -# Meat
!! \endcode
!! You can use all the \f$\LaTeX\f$,
!! <A HREF="http://www.doxygen.nl/manual/markdown.html">Markdown</A> and
!! <A HREF="http://www.doxygen.nl/manual/htmlcmds.html">HTML commands</A>
!! described above and in the
!! <A HREF="http://www.doxygen.nl/manual/index.html"> Doxygen documentation
!! </A>:
!! \code{.unparsed}
!!   !! \section run_analysis Post-Cal&ccedil;otada Analysis
!!   !! If you lose track of how many cal&ccedil;cots you have eaten, this
!!   !! can be estimated from the integrated area of Romesco sauce on
!!   !! your clothes:
!!   !! \f[
!!   !!   n_{cal} = \frac{1}{\mathrm{C}} \iint_{A} R(A) \:d A
!!   !! \f]
!!   !! where \f$\mathrm{C}\f$ is a constant that is typically estimated as
!!   !! \f$\mathrm{C = 1.2 \: cm^2 \: calcot^{-1}}\f$.
!! \endcode
!!
!! The above example will generate the How-To shown \subpage how_to_calcot "here".
!!
!! Remeber to add your How-To to the \ref how_tos "How To List":
!! \code{.unparsed}
!!   !! - \ref how_to_calcot
!! \endcode
!!
!! \section doc_config_files Configuration File Formats
!!
!! \todo Develop a structure for documenting configuration files for MONARCH
!! and update this section (see issue:
!! https://earth.bsc.es/gitlab/ac/nmmb-monarch/issues/101 )
!!

!*******************************************************************************

!> \page how_to_calcot Cal&ccedil;otada
!!
!! (This page is an example How-To generated from code in the
!! \ref doc_how_tos "How to create How-To's" page.)
!!
!! Cal&ccedil;otadas are {finish}
!! \section calcot_planning Planning
!!
!! \subsection calcot_planning_timing Timing
!!   Cal&ccedil;otadas are typically held in the late winter
!!   or early spring.
!!
!! \subsection calcot_planning_location Location
!!   Try to find an outdoor location with a place to make
!!   a fire to cook the cal&ccedil;ots.
!!
!! \subsection calcot_planning_shopping Shopping List
!!   -# Cal&ccedil;ots
!!   -# Romesco sauce
!!   -# Meat
!! \section run_analysis Post-Cal&ccedil;otada Analysis
!! If you lose track of how many cal&ccedil;cots you have eaten, this
!! can be estimated from the integrated area of Romesco sauce on
!! your clothes:
!! \f[
!!   n_{cal} = \frac{1}{\mathrm{C}} \iint_{A} R(A) \: d A
!! \f]
!! where \f$\mathrm{C}\f$ is a constant that is typically estimated as
!! \f$\mathrm{C = 1.2 \: cm^2 \: calcot^{-1}}\f$.