add:doc:document the sanity check steps and add a note about the Java code

1 files changed, 88 insertions, 59 deletions

diff --git a/docs/development/programming_guidelines.rst b/docs/development/programming_guidelines.rst
index 3aecabcf7..c04f8daab 100644
--- a/docs/development/programming_guidelines.rst
+++ b/docs/development/programming_guidelines.rst
@@ -5,6 +5,26 @@ Programming guidelines
 NAVIT is a team-project, thus a lot of coders are working on it's development and code base.
 To get a unified coding style and make it easier for everybody to work with parts, that someone else wrote, we tried to specify the formatting of our source and how we deal with third party modules as following.
 
+Enforced guidelines via CircleCI
+================================
+
+The 1st step of the checks enforced after a PR is created or updated is what we call "sanity checks".
+Those enforce the coding style for our C and Java files. During this phase we have several steps:
+ * verification that the modified files don't contain trailing spaces.
+   You can use `sed 's/\s*$//' -i "$f"` if you want to clean your files before pushing your PR.
+ * verification that the style of our C and C++  code is respected using `astyle`
+   (to the exception of the following folders: `navit/support/`, `navit/fib-1.1/`, `navit/traffic/permanentrestrictions/`).
+   You can use the following command on the files you are modifying (replacing `$f` by your file name):
+   `astyle --indent=spaces=4 --style=attach -n --max-code-length=120 -xf -xh "${f}"`
+ * check for compliance with the DTD using xmllint on the modified files. You can check this locally by using:
+   `xmllint --noout --dtdvalid navit/navit.dtd "$f"`
+ * verification that the style of our Java code follows our standards using `./gradlew checkstyleMain`
+
+.. note::
+
+  When you submit a PR make sure your branch is up-to-date with the trunk branch to avoid having checks on files you did
+  not modified.
+
 Coding Style
 ============
 
@@ -18,14 +38,14 @@ To help us keeping a coherent indentation, we use astyle on C, C++ and java file
 
 .. code-block:: C
 
-    astyle --indent=spaces=4 --style=attach -n --max-code-length=120 -xf -xh my_file.c
+  astyle --indent=spaces=4 --style=attach -n --max-code-length=120 -xf -xh my_file.c
 
 
 .. note::
 
-    Because of the bug: [https://sourceforge.net/p/astyle/bugs/230/](https://sourceforge.net/p/astyle/bugs/230/) on astyle,
-    we cannot rely on astyle to handle properly the line length of 120 characters that we choose.
-    It would be recommended to set that line length in the editor you are using.
+  Because of the bug: [https://sourceforge.net/p/astyle/bugs/230/](https://sourceforge.net/p/astyle/bugs/230/) on astyle,
+  we cannot rely on astyle to handle properly the line length of 120 characters that we choose.
+  It would be recommended to set that line length in the editor you are using.
 
 Character encoding and line breaks
 ----------------------------------
@@ -42,20 +62,20 @@ Instead of
 
 .. code-block:: C
 
-    {
-       do_something();
-       int a=do_something_else();
-    }
+  {
+     do_something();
+     int a=do_something_else();
+  }
 
 use
 
 .. code-block:: C
 
-    {
-       int a;
-       do_something();
-       a=do_something_else();
-    }
+  {
+     int a;
+     do_something();
+     a=do_something_else();
+  }
 
  * No dynamic arrays
 
@@ -63,17 +83,17 @@ Instead of
 
 .. code-block:: C
 
-    void myfunc(int count) {
-       struct mystruct x[count]
-    }
+  void myfunc(int count) {
+     struct mystruct x[count]
+  }
 
 use
 
 .. code-block:: C
 
-    void myfunc(int count) {
-       struct mystruct *x=g_alloca(count*sizeof(struct mystruct));
-    }
+  void myfunc(int count) {
+     struct mystruct *x=g_alloca(count*sizeof(struct mystruct));
+  }
 
  * No empty initializers
 
@@ -81,19 +101,19 @@ Instead of
 
 .. code-block:: C
 
-    struct mystruct m={};
+  struct mystruct m={};
 
 use
 
 .. code-block:: C
 
-    struct mystruct m={0,};
+  struct mystruct m={0,};
 
 * Use `/*` and `*/` for comments instead of `//`
 
 .. note::
 
-    The restriction to C95 exists mainly to help the [[WinCE]] port, which uses a compiler without full support for C99. Once all platforms supported by Navit use a compiler capable of C99, this decision may be reconsidered.
+  The restriction to C95 exists mainly to help the [[WinCE]] port, which uses a compiler without full support for C99. Once all platforms supported by Navit use a compiler capable of C99, this decision may be reconsidered.
 
 
 Use of libraries
@@ -121,18 +141,18 @@ Example :
 
 .. code-block:: C
 
-    /**
-    * @brief Change the current zoom level, zooming closer to the ground.
-    *
-    * This sentence starts the "detailed" description (because this is a new
-    * paragraph).
-    *
-    * @param navit The navit instance
-    * @param factor The zoom factor, usually 2
-    * @param p The invariant point (if set to NULL, default to center)
-    * @returns nothing
-    */
-    void navit_zoom_in(struct navit *this_, int factor, struct point *p)
+  /**
+  * @brief Change the current zoom level, zooming closer to the ground.
+  *
+  * This sentence starts the "detailed" description (because this is a new
+  * paragraph).
+  *
+  * @param navit The navit instance
+  * @param factor The zoom factor, usually 2
+  * @param p The invariant point (if set to NULL, default to center)
+  * @returns nothing
+  */
+  void navit_zoom_in(struct navit *this_, int factor, struct point *p)
 
 Templates
 `````````
@@ -144,18 +164,18 @@ Files
 
 .. code-block:: C
 
-    /** @file can.cpp
-     * @brief CAN-Camera Framework :: CAN container class and high level functions
-     *
-     * Some documentation regarding this file.
-     *
-     * @Author Stefan Klumpp <sk@....>
-     * @date 2008
-     */
-    <include "can.h">
-    .
-    .
-    .
+  /** @file can.cpp
+   * @brief CAN-Camera Framework :: CAN container class and high level functions
+   *
+   * Some documentation regarding this file.
+   *
+   * @Author Stefan Klumpp <sk@....>
+   * @date 2008
+   */
+  <include "can.h">
+  .
+  .
+  .
 
 Classes/Structs/Functions/Methods
 '''''''''''''''''''''''''''''''''
@@ -163,18 +183,27 @@ Classes/Structs/Functions/Methods
 
 .. code-block:: C
 
-    /**
-     * @brief A short description of this function
-     *
-     * A lot more of documentation regarding this function.
-     * @param raw_data Some string to pass to the function
-     * @return Nothing
-     */
-
-    void CanData::processData(string &raw_data) {
-    .
-    .
-    .
-    }
+  /**
+   * @brief A short description of this function
+   *
+   * A lot more of documentation regarding this function.
+   * @param raw_data Some string to pass to the function
+   * @return Nothing
+   */
+
+  void CanData::processData(string &raw_data) {
+  .
+  .
+  .
+  }
+
+
+Java standards
+--------------
+
+For the Java code we follow the Google coding conventions from Google Java Style that can be found at `<https://google.github.io/styleguide/javaguide.html>`_.
+
+This style is enforced by using Checkstyle. Its definition file can be found at the root of the repository:
+`checkstyle.xml <https://github.com/navit-gps/navit/blob/trunk/checkstyle.xml>`_
 
 Please add yourself to the list of authors, if you make a significant change.