Skip to content
GitLab
Projects Groups Snippets
  • /
  • Help
    • Help
    • Support
    • Community forum
    • Submit feedback
    • Contribute to GitLab
  • Sign in / Register
  • dumux dumux
  • Project information
    • Project information
    • Activity
    • Labels
    • Members
  • Repository
    • Repository
    • Files
    • Commits
    • Branches
    • Tags
    • Contributors
    • Graph
    • Compare
  • Issues 104
    • Issues 104
    • List
    • Boards
    • Service Desk
    • Milestones
  • Merge requests 92
    • Merge requests 92
  • CI/CD
    • CI/CD
    • Pipelines
    • Jobs
    • Schedules
  • Deployments
    • Deployments
    • Environments
    • Releases
  • Packages and registries
    • Packages and registries
    • Container Registry
  • Monitor
    • Monitor
    • Incidents
  • Analytics
    • Analytics
    • Value stream
    • CI/CD
    • Repository
  • Wiki
    • Wiki
  • Activity
  • Graph
  • Create a new issue
  • Jobs
  • Commits
  • Issue Boards
Collapse sidebar
  • dumux-repositoriesdumux-repositories
  • dumuxdumux
  • Merge requests
  • !1351

Cleanup/doxygen for 3.0

  • Review changes

  • Download
  • Email patches
  • Plain diff
Merged Simon Emmert requested to merge cleanup/doxygen-for-3.0 into master Nov 27, 2018
  • Overview 5
  • Commits 24
  • Pipelines 0
  • Changes 254

When checking doxygen, the doxygen should be built and the doxyerr.log should have as little lines/errors as possible. We currently have around 1800 lines of errors and want to reduce this to 1 to 7 lines.

The Doxygen for a file should look like this:

/*!
 * \file
 * \ingroup Common
 * \brief Manages the handling of time dependent problems
 */

It should always contain the \file first. The \ingroup gives a Group that is as precise as possible and is part of the modules.txt The \brief is a short comment on what happens in the file. Alternatively a \copybrief could be used. Make sure the copybrief links to the correct section and is not ambigous! Additional text could be added similar to the function description.

A class could look like this:

/*!
 * \ingroup Common
 * \brief Manages the handling of time dependent problems.
 *
 * This class facilitates the time management of the simulation.
 * It doesn't manage [...]
 * [...]
 * [...] index starting at 0.
 *
 * \note Time and time step sizes are in units of seconds
 */

The class should always have the proper \ingroup just like the file. The \brief should always contain a short description, and only in very very rare occasions a class can have a \copybrief. In the end this is also documentation for users that do not build doxygen and \copybriefs from another file are most likely not very useful. The main part should be an in depth explanation of what is done. This should contain math-expressions where applicable. They can look like the following:

 * This class implements a spline \f$s(x)\f$ for which, given \f$n\f$ sampling
 * points \f$x_1, \dots, x_n\f$, the following conditions hold
 *\f{align*}{
   s(x_i)   & = y_i \quad \forall i \in \{1, \dots, n \}\\
   s'(x_1)  & = m_1 \\
   s'(x_n)  & = m_n
   \f}
*

For a function in a file the Doxygen can look like this:

/*!
 * \brief Set the current simulated time and the time step index.
 *
 * \param t The time \f$\mathrm{[s]}\f$ which should be jumped to
 * \param stepIdx The new time step index
 */
 void setTime(Scalar t, int stepIdx)
     { time_ = t; timeStepIdx_ = stepIdx; }

The function has a short comment with the \brief. If there are function-arguments that are not self-explanatory, they should be described using \param.** Always explain all params or no params at all!** Otherwise Doxygen will throw an error. Additional Doxygen-commands that might be useful are \note for giving an important note/hint on what the function does as well as \return which specifies the return value (if applicable).

We will go through the errors according to folders:

  • freeflow (262) @nedc
  • material (209) @ackerm
  • multidomain (168)
  • porousmediumflow (558) @scholz
  • common, discretization, geomechanics @hommel
  • nonlinear,io,linear, material, nonlinear, parallel

Fix/Document everything according to the guideline. If there is a problem with a copybrief try to fix it or contact @scholz for help.

Closes #596 (closed)

Edited Nov 29, 2018 by Simon Emmert
Assignee
Assign to
Reviewers
Request review from
Time tracking
Source branch: cleanup/doxygen-for-3.0