From 844d880ee97c51285dc1829fdc03654b7fee25eb Mon Sep 17 00:00:00 2001 From: Matthias Maier Date: Fri, 15 Jun 2018 22:49:07 -0500 Subject: [PATCH] update documentation --- contrib/utilities/indent | 21 ++++++++++++++------- contrib/utilities/indent-branch | 16 ++++++++++++---- doc/doxygen/headers/coding_conventions.h | 16 +++++++++------- 3 files changed, 35 insertions(+), 18 deletions(-) diff --git a/contrib/utilities/indent b/contrib/utilities/indent index 54e2ced7b6..afa726ce42 100755 --- a/contrib/utilities/indent +++ b/contrib/utilities/indent @@ -15,20 +15,27 @@ ## --------------------------------------------------------------------- # -# This script indents all source files of deal.II according to our -# usual code formatting standards. It is used to ensure that our -# code base looks uniform, as uniformity helps make code easier to -# read. +# This script indents all source files of deal.II according to our usual +# code formatting standards. It is used to ensure that our code base looks +# uniform, as uniformity helps make code easier to read. # # While we're already touching every file, this script also makes -# sure we set permissions correctly +# sure we set permissions correctly and checks for correct unix-style line +# endings. # # The script needs to be executed as -# ./contrib/utilities/indent +# $ ./contrib/utilities/indent # from the top-level directory of the source tree, or via -# make indent +# $ make indent # from a build directory. # +# Note: If the script is invoked with REPORT_ONLY=true set, +# $ REPORT_ONLY=true ./contrib/utilities/indent +# or, +# $ make REPORT_ONLY=true indent +# then indentation errors will only be reported without any actual file +# changes. +# if [ ! -f contrib/utilities/indent_common.sh ]; then echo "*** This script must be run from the top-level directory of deal.II." diff --git a/contrib/utilities/indent-branch b/contrib/utilities/indent-branch index 46f1412d58..e2bed13546 100755 --- a/contrib/utilities/indent-branch +++ b/contrib/utilities/indent-branch @@ -17,13 +17,21 @@ # # This script does the same thing as contrib/utilities/indent but only # reformats files which have changed (or have been added but neither -# staged/commited) since the last merge commit to the master branch. It -# should be run as -# -# make indent-branch +# staged/commited) since the last merge commit to the master branch. # +# The script needs to be executed as +# $ ./contrib/utilities/indent-branch +# from the top-level directory of the source tree, or via +# $ make indent-branch # from a build directory. # +# Note: If the script is invoked with REPORT_ONLY=true set, +# $ REPORT_ONLY=true ./contrib/utilities/indent-branch +# or, +# $ make REPORT_ONLY=true indent-branch +# then indentation errors will only be reported without any actual file +# changes. +# if [ ! -f contrib/utilities/indent_common.sh ]; then echo "*** This script must be run from the top-level directory of deal.II." diff --git a/doc/doxygen/headers/coding_conventions.h b/doc/doxygen/headers/coding_conventions.h index 7cecc12ab0..2cedd9cd3b 100644 --- a/doc/doxygen/headers/coding_conventions.h +++ b/doc/doxygen/headers/coding_conventions.h @@ -50,14 +50,16 @@ on each of your files. This will make sure indentation is conforming to the style guidelines outlined in this page. Alternatively, you can run
-  make indent
+  make indent-branch
 
in whatever directory you set up the library to be compiled in to indent all -source files. If you want to make sure that the indenting is correct for all -your commits, you might want to set up a pre-commit hook. One way to do so, -is to copy ${SOURCE_DIR}/contrib/scripts/pre-commit-clang-format to -${SOURCE_DIR}/.git/hooks/pre-commit and make sure it is executable. +source files that have been changed recently. If you want to make sure that +the indenting is correct for all your commits, you might want to set up a +pre-commit hook. One way to do so, is to copy +${SOURCE_DIR}/contrib/scripts/pre-commit-clang-format to +${SOURCE_DIR}/.git/hooks/pre-commit and make sure it is +executable.

Style issues

@@ -67,8 +69,8 @@ ${SOURCE_DIR}/.git/hooks/pre-commit and make sure it is executable. degrees of freedom, etc) should start with n_*. Example: SparsityPattern::n_nonzero_entries(). -
  • %Function which set a bit or flag should start with set_*; - functions which clear bits of flags should be named clear_*. +
  • %Functions which set a bit or flag should start with set_*; + functions which clear bits or flags should be named clear_*. Example: CellIterator::set_refine_flag().
  • Traditional logical operators should be used instead of their English -- 2.39.5