From fa7d476557a5c5c7585491ed03e4ee22cedb0b9b Mon Sep 17 00:00:00 2001
From: Timo Koch <timo.koch@iws.uni-stuttgart.de>
Date: Wed, 25 Jul 2018 12:44:38 +0200
Subject: [PATCH] [contribting] Fix formatting

---
 CONTRIBUTING.md   |  19 +++--
 doc/styleguide.md | 187 ++++++++++++++++++++++++----------------------
 2 files changed, 108 insertions(+), 98 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b798be5d51..5ea99ad00e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -10,7 +10,7 @@ here are many easy things that you can do, like
 If you decide to contribute code please read this contribution guide.
 
 ## Style guide
-When contributing code to DuMu<sup>x</sup> please follow the [styleguide](doc/styleguide.md). Your work will enjoy much smoother sailing if stick to it with your changes. DuMu<sup>x</sup> is a pretty large project, and a consistent way of doing things really helps a lot when trying to find your way around the code.
+When contributing code to DuMu<sup>x</sup> please follow the [style guide](doc/styleguide.md). Your work will enjoy much smoother sailing if stick to it with your changes. DuMu<sup>x</sup> is a pretty large project, and a consistent way of doing things really helps a lot when trying to find your way around the code.
 
 ## Contributing
 
@@ -29,17 +29,20 @@ DuMu<sup>x</sup> mailing list.
 
 ## Git
 * Use git to your advantage!
-* Check out this (great tutorial)[https://www.atlassian.com/git/tutorials/setting-up-a-repository] in order to learn how to use it
+* Check out this [great tutorial](https://www.atlassian.com/git/tutorials/setting-up-a-repository) in order to learn how to use it
+* Also check out [Dune's git best practices](https://www.dune-project.org/doc/guides/git_best_practices/)
 * Everything should compile after every single commit
 * Make small commits with changes limited to a single issue / change
 * Format commit messages as follows
-```
-[topic] Brief description of the change
 
-Long description containing the status quo,
-the changes the commit introduces and why.
-```
-where `topic` is usually a foldername, `[assembly]`, a model `[2p2c]`, or any other topic, e.g. `[cmake]`.
+    ```
+    [topic] Brief description of the change
+
+    Long description containing the status quo,
+    the changes the commit introduces and why.
+    ```
+
+    where `topic` is usually a foldername, `[assembly]`, a model `[2p2c]`, or any other topic, e.g. `[cmake]`.
 
 * Use `git rebase -i master` to update branches to the changes on the master branch
 * feature branches should be called `feature/my-bla-feature`
diff --git a/doc/styleguide.md b/doc/styleguide.md
index f17f718ddf..cd9a708982 100644
--- a/doc/styleguide.md
+++ b/doc/styleguide.md
@@ -7,7 +7,6 @@
 * In contrast to the remainder of the coding style guidelines, these code formatting rules are (partially) enforced automatically with a pre-commit hook. Due to the distributed nature of git, this hook can only check your commits once they arrive in the central repository, so it is important to make your local git repository check your commits as well. The dunecontrol script will automatically install such a pre-commit hook for you.
 
 
-
 ## C++
 
 ### Documentation
@@ -15,71 +14,79 @@
 * Please document freely what each part of your code _should_ do. Document assumptions.
 * All comments/documentation in English.
 * We proclaim the Doc-Me dogma, which means whatever you do, please document it at least with
-  ```c++
-  //! \todo Please doc me!
-  ```
+
+    ```c++
+    //! \todo Please doc me!
+    ```
+
 * We use doxygen to generate documentation from the source code
-  ```c++
-  int lineOfCode = 1; // Short comment on line of code 1 that will _not_ show in doxygen
-  int lineOfCode = 2; //!< Short comment on line of code 2 that will show in doxygen
-  //! Short comment on the following line (line of code 3) that will show in doxygen
-  int lineOfCode = 3;
-  /*!
-   * Longer comment on line of code 4
-   * with several lines of length
-   * that will show in doxygen
-   */
-  int lineOfCode = 4;
-  ```
+
+    ```c++
+    int lineOfCode = 1; // Short comment on line of code 1 that will _not_ show in doxygen
+    int lineOfCode = 2; //!< Short comment on line of code 2 that will show in doxygen
+    //! Short comment on the following line (line of code 3) that will show in doxygen
+    int lineOfCode = 3;
+    /*!
+     * Longer comment on line of code 4
+     * with several lines of length
+     * that will show in doxygen
+     */
+    int lineOfCode = 4;
+    ```
 
 * Files always contain the following documentation header before the headerguard
-  ```c++
-  /*!
-   * \file
-   * \ingroup GroupName
-   * \brief A short description of the file.
-   */
-  #ifndef DUMUX_HEADERGUARD_HH
-  #define DUMUX_HEADERGUARD_HH
-  ```
-  where `GroupName` is a doxygen module group, click [here](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/blob/master/doc/doxygen/modules.txt) for an overview of existing groups.
+
+    ```c++
+    /*!
+     * \file
+     * \ingroup GroupName
+     * \brief A short description of the file.
+     */
+    #ifndef DUMUX_HEADERGUARD_HH
+    #define DUMUX_HEADERGUARD_HH
+    ```
+
+    where `GroupName` is a doxygen module group, click [here](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/blob/master/doc/doxygen/modules.txt) for an overview of existing groups.
 
 * Each class should be documented using the following style
-  ```c++
-  /*!
-   * \ingroup GroupName
-   * \brief A short description of the class.
-   *
-   * Optional detailed description of the class
-   * over several lines.
-   *
-   * \tparam T very short description of the template parameter T
-   */
-  template<class T>
-  class MyClass {};
-  ```
+
+    ```c++
+    /*!
+     * \ingroup GroupName
+     * \brief A short description of the class.
+     *
+     * Optional detailed description of the class
+     * over several lines.
+     *
+     * \tparam T very short description of the template parameter T
+     */
+    template<class T>
+    class MyClass {};
+    ```
 
 * Each free function and class member function should be documented using the following style
-  ```c++
-  /*!
-   * \brief A short description of the function.
-   *
-   * Optional detailed description of the function
-   * over several lines.
-   *
-   * \tparam paramType Very short description of paramType
-   * \param paramName Very short description of paramName
-   * \return returnName Very short description of returnName
-   */
-  template<typename paramType>
-  paramType functionName(const paramType& paramName)
-  {
+
+    ```c++
+    /*!
+     * \brief A short description of the function.
+     *
+     * Optional detailed description of the function
+     * over several lines.
+     *
+     * \tparam paramType Very short description of paramType
+     * \param paramName Very short description of paramName
+     * \return returnName Very short description of returnName
+     */
+    template<typename paramType>
+    paramType functionName(const paramType& paramName)
+    {
       ...
       return returnName
-  }
-  ```
+    }
+    ```
 
 * Also document non-obvious function parameters at call site
+
     ```c++
     localResidual.eval(/*includeBoundaries=*/true);
     ```
@@ -117,10 +124,11 @@
 * Header files get the suffix `.hh`, implementation files the suffix `.cc`
 * Every header file contains a unique header guard. The name should mimic the folder structure, and contain the filename,
   i.e. for a file `common/myfile.hh` it should be
-  ```c++
-  #ifndef DUMUX_COMMON_MYFILE_HH
-  #define DUMUX_COMMON_MYFILE_HH
-  ```
+
+    ```c++
+    #ifndef DUMUX_COMMON_MYFILE_HH
+    #define DUMUX_COMMON_MYFILE_HH
+    ```
 
 #### Macros
 * The use of preprocessor macros is strongly discouraged. If you have to use them for whatever reason, please use capital letters only.
@@ -136,36 +144,36 @@
 * There should be a space between `if`,`else if`,`switch` and the condition
 * `if`,`else if`,`switch` can omit brackets if the expression is only one line
 
-```c++
-// comment for if block, space between if and (enableGravity)
-if (enableGravity)
-{
-    Scalar b = 1.0;
-    return b*gravity_[dimWorld-1];
-}
-
-// comment for else-block
-else
-    return 1.0; // ok, one-liner
-```
+    ```c++
+    // comment for if block, space between if and (enableGravity)
+    if (enableGravity)
+    {
+        Scalar b = 1.0;
+        return b*gravity_[dimWorld-1];
+    }
+
+    // comment for else-block
+    else
+        return 1.0; // ok, one-liner
+    ```
 
 ### Namespaces
 
 * Open curly brackets on the same line
 * Do not indent the code inside the namespace
 * Comment closing curly brackets uniquely
-__Example:__
 
-```c++
-namespace Dumux {
-namespace Properties {
+    ```c++
+    namespace Dumux {
+    namespace Properties {
+
+    bool here = true;
+        bool nothere = false; // not like this
 
-bool here = true;
-    bool nothere = false; // not like this
+    } // end namespace Properties
+    } // end namespace Dumux
+    ```
 
-} // end namespace Properties
-} // end namespace Dumux
-```
 * Use a `Detail` namespace for hiding implementation details, e.g. for template meta programming
 
 ### Includes
@@ -175,11 +183,11 @@ bool here = true;
 * Always use project relative paths
     - exception: the other header is in the same folder and closely related (`#include "volumevariables.hh"`)
 
-```c++
-#include <type_traits>
-#include <dune/common/fvector.hh>
-#include <dumux/common/exceptions.hh>
-```
+    ```c++
+    #include <type_traits>
+    #include <dune/common/fvector.hh>
+    #include <dumux/common/exceptions.hh>
+    ```
 
 ### Property system
 
@@ -201,11 +209,10 @@ bool here = true;
 * Folder names are lower case only
 * Tests should be called after model and discretization scheme using underscores and lower case only, e.g.
 
-__Example:__
-```
-test_1p_tpfa
-test_2p2c_box_infiltration
-```
+    ```
+    test_1p_tpfa
+    test_2p2c_box_infiltration
+    ```
 
 ## CMake
 
-- 
GitLab