Add experimental .clang-format

This adds a configuration file for clang-format [1] and a test file to
demonstrate benefits and current problems with respect to Qt Creator's
coding rules [2].

This is based on clang-format from the llvm/clang 5.0 branch, which is
about to be released soon in the next days/weeks (already behind
schedule).

Using clang-format for Qt Creator brings these advantages:
 * Enforce a bunch of coding rules by a simple tool/shortcut invocation.
 * Spend less review cycles for authors and reviewers regarding
   formatting. This helps especially for/with first-time contributors.
 * clang-format sorts includes and using declarations.
 * clang-format adds/updates namespace end comments, e.g.: } //
   namespace Foo

See dist/clangformat/README.md for setup instructions und currently
known issues.

[1] https://clang.llvm.org/docs/ClangFormat.html
[2] https://doc-snapshots.qt.io/qtcreator-extending/coding-style.html

Task-number: QTCREATORBUG-17643
Change-Id: I87bdd66b8e492e99a360022962b0053f02a33e57
Reviewed-by: Alessandro Portale <alessandro.portale@qt.io>
Reviewed-by: Eike Ziller <eike.ziller@qt.io>

2 files changed, 271 insertions, 0 deletions

diff --git a/dist/clangformat/.clang-format b/dist/clangformat/.clang-format
new file mode 100644
index 0000000000..25df05eb26
--- /dev/null
+++ b/dist/clangformat/.clang-format
@@ -0,0 +1,115 @@
+# .clang-format for Qt Creator
+#
+# This is for clang-format >= 5.0.
+#
+# The configuration below follows the Qt Creator Coding Rules [1] as closely as
+# possible. For documentation of the options, see [2].
+#
+# Use ../../tests/manual/clang-format-for-qtc/test.cpp for documenting problems
+# or testing changes.
+#
+# [1] https://doc-snapshots.qt.io/qtcreator-extending/coding-style.html
+# [2] https://clang.llvm.org/docs/ClangFormatStyleOptions.html
+#
+---
+Language:        Cpp
+AccessModifierOffset: -4
+AlignAfterOpenBracket: Align
+AlignConsecutiveAssignments: false
+AlignConsecutiveDeclarations: false
+AlignEscapedNewlines: DontAlign
+AlignOperands:   true
+AlignTrailingComments: true
+AllowAllParametersOfDeclarationOnNextLine: true
+AllowShortBlocksOnASingleLine: false
+AllowShortCaseLabelsOnASingleLine: false
+AllowShortFunctionsOnASingleLine: Inline
+AllowShortIfStatementsOnASingleLine: false
+AllowShortLoopsOnASingleLine: false
+AlwaysBreakAfterReturnType: None
+AlwaysBreakBeforeMultilineStrings: false
+AlwaysBreakTemplateDeclarations: true
+BinPackArguments: false
+BinPackParameters: false
+BraceWrapping:
+  AfterClass:      true
+  AfterControlStatement: false
+  AfterEnum:       false
+  AfterFunction:   true
+  AfterNamespace:  false
+  AfterObjCDeclaration: false
+  AfterStruct:     true
+  AfterUnion:      false
+  BeforeCatch:     false
+  BeforeElse:      false
+  IndentBraces:    false
+  SplitEmptyFunction: false
+  SplitEmptyRecord: false
+  SplitEmptyNamespace: false
+BreakBeforeBinaryOperators: All
+BreakBeforeBraces: Custom
+BreakBeforeInheritanceComma: false
+BreakBeforeTernaryOperators: true
+BreakConstructorInitializersBeforeComma: false
+BreakConstructorInitializers: BeforeComma
+BreakAfterJavaFieldAnnotations: false
+BreakStringLiterals: false
+ColumnLimit:    100
+CommentPragmas:  '^ IWYU pragma:'
+CompactNamespaces: false
+ConstructorInitializerAllOnOneLineOrOnePerLine: false
+ConstructorInitializerIndentWidth: 4
+ContinuationIndentWidth: 4
+Cpp11BracedListStyle: true
+DerivePointerAlignment: false
+DisableFormat:   false
+ExperimentalAutoDetectBinPacking: false
+FixNamespaceComments: true
+ForEachMacros:
+  - forever # avoids { wrapped to next line
+  - foreach
+  - Q_FOREACH
+  - BOOST_FOREACH
+IncludeCategories:
+  - Regex:           '^<Q.*'
+    Priority:        200
+IncludeIsMainRegex: '(Test)?$'
+IndentCaseLabels: false
+IndentWidth:     4
+IndentWrappedFunctionNames: false
+JavaScriptQuotes: Leave
+JavaScriptWrapImports: true
+KeepEmptyLinesAtTheStartOfBlocks: false
+# Do not add QT_BEGIN_NAMESPACE/QT_END_NAMESPACE as this will indent lines in between.
+MacroBlockBegin: ""
+MacroBlockEnd:   ""
+MaxEmptyLinesToKeep: 1
+NamespaceIndentation: None
+ObjCBlockIndentWidth: 4
+ObjCSpaceAfterProperty: false
+ObjCSpaceBeforeProtocolList: true
+PenaltyBreakAssignment: 150
+PenaltyBreakBeforeFirstCallParameter: 300
+PenaltyBreakComment: 500
+PenaltyBreakFirstLessLess: 400
+PenaltyBreakString: 600
+PenaltyExcessCharacter: 50
+PenaltyReturnTypeOnItsOwnLine: 300
+PointerAlignment: Right
+ReflowComments:  false
+SortIncludes:    true
+SortUsingDeclarations: true
+SpaceAfterCStyleCast: true
+SpaceAfterTemplateKeyword: false
+SpaceBeforeAssignmentOperators: true
+SpaceBeforeParens: ControlStatements
+SpaceInEmptyParentheses: false
+SpacesBeforeTrailingComments: 1
+SpacesInAngles:  false
+SpacesInContainerLiterals: false
+SpacesInCStyleCastParentheses: false
+SpacesInParentheses: false
+SpacesInSquareBrackets: false
+Standard:        Cpp11
+TabWidth:        4
+UseTab:          Never
diff --git a/dist/clangformat/README.md b/dist/clangformat/README.md
new file mode 100644
index 0000000000..ae714aad9e
--- /dev/null
+++ b/dist/clangformat/README.md
@@ -0,0 +1,156 @@
+# .clang-format for Qt Creator
+
+Alongside this file you find an EXPERIMENTAL .clang-format configuration file
+for the Qt Creator code base.
+
+The current configuration is useful, but not fully in accordance with the
+coding rules. There is also other undesired formatting. Running clang-format
+blindly will not only improve formatting here and there, but will also
+normalize/worsen code that is already considered ideally formatted. See section
+"Coding rules violated by clang-format" below for more information.
+
+If needed, clang-format can be instructed to not format code ranges. Do not
+overuse this.
+
+    // clang-format off
+        void    unformatted_code  ;
+    // clang-format on
+
+For more information about clang-format, see
+
+      <https://clang.llvm.org/docs/ClangFormat.html>
+
+## Prerequisites
+
+ * clang-format >= 5.0
+
+## Set up Qt Creator for use with clang-format
+
+### Install the configuration file
+
+For a given source file to format, clang-format it will read the configuration
+from .clang-format in the closest parent directory for the file to format.
+
+Hence symlink/copy .clang-format from this directory to e.g. Qt Creator's top
+level directory:
+
+For Linux/macOS:
+
+    $ cd $QTC_SOURCE
+    $ ln -s dist/clangformat/.clang-format
+
+For Windows:
+
+    $ cd $QTC_SOURCE
+    $ copy dist\clangformat\.clang-format # Do not forget to keep this updated
+
+### Configure Qt Creator
+
+  1. Enable the Beautifier plugin and restart to load it.
+
+  2. Configure the plugin:
+     In Menu: Tools > Options > Beautifier > Tab: Clang Format
+      * Select a valid clang-format executable
+      * Use predefined style: File
+          * Fallback style: None
+
+  3. Set shortcuts for convenience:
+     In Menu: Tools > Options > Environment > Keyboard
+      * ClangFormat / FormatFile - e.g. Alt+C, F
+      * ClangFormat / FormatSelectedText - e.g. Alt+C, S
+
+Due to several issues outlined below the FormatFile action might be of limited
+use.
+
+## Coding rules enforced by clang-format
+
+This is a copy-pasted list of coding rules from
+<https://doc-snapshots.qt.io/qtcreator-extending/coding-style.html> that can be
+enforced with the current configuration:
+
+* Formatting
+  * Whitespace
+    * Use four spaces for indentation, no tabs.
+    * Always use only one blank line (to group statements together)
+    * Pointers and References: For pointers or references, always use a single
+      space before an asterisk (*) or an ampersand (&), but never after.
+    * Operator Names and Parentheses: Do not use spaces between operator names
+      and parentheses.
+    * Function Names and Parentheses: Do not use spaces between function names
+      and parentheses.
+    * Keywords: Always use a single space after a keyword, and before a curly
+      brace.
+  * Braces
+    * As a base rule, place the left curly brace on the same line as the start
+      of the statement.
+    * Exception: Function implementations and class declarations always have
+      the left brace in the beginning of a line
+  * Line Breaks
+    * Keep lines shorter than 100 characters
+    * Insert line breaks if necessary.
+    * Commas go at the end of a broken line.
+    * Operators start at the beginning of the new line.
+  * Namespaces:
+    * Put the left curly brace on the same line as the namespace keyword.
+    * Do not indent declarations or definitions inside.
+    * Optional, but recommended if the namespaces spans more than a few lines:
+      Add a comment after the right curly brace repeating the namespace.
+* Patterns and Practices
+  * C++11 and C++14 Features / Lambdas:
+    * Optionally, place the lambda completely on one line if it fits.
+    * Place a closing parenthesis and semicolon of an enclosing function call
+      on the same line as the closing brace of the lambda.
+
+## Coding rules violated by clang-format
+
+* Formatting / Namespaces
+  * As an exception, if there is only a single class declaration inside the
+    namespace, all can go on a single line.  Currently this ends up on several
+    lines, which is noisy.
+* Patterns and Practices / C++11 and C++14 Features / Lambdas
+  * If you are using a lambda in an 'if' statement, start the lambda on a new
+    line.
+
+### Other undesired formattings
+
+For a more complete list of observations and problems, see the "// NOTE: "
+comments in ../../tests/manual/clang-format-for-qtc/test.cpp.
+
+#### Manually aligned complex expressions in e.g. if-conditions are collapsed
+
+We want:
+
+    if (someFancyAndLongerExpression1
+            || someFancyAndLongerExpression2
+            || someFancyAndLongerExpression3) {
+        return value;
+    }
+
+Current:
+
+    if (someFancyAndLongerExpression1 || someFancyAndLongerExpression2
+        || someFancyAndLongerExpression3) {
+        return value;
+    }
+
+#### connect() calls do not follow the standard two-line pattern
+
+In general, for middle-sized and longer connect() calls we want to follow this
+two-line pattern.
+
+    connect(sender, &SomeFancySender::signal,
+            receiver, &SomeFancyReceiver::slot);
+
+Current:
+
+    connect(sender,
+            &SomeFancySender::signal,
+            receiver,
+            &SomeFancySender::slot);
+
+#### QTC_ASSERT and excess space after return keyword
+
+For QTC_ASSERT in combination with the return keyword, an excess space is added:
+
+    QTC_ASSERT(headItem, return );
+