[tracker/sam/uncrustify: 1/8] Improve Uncrustify configuration

[Sam Thursfield <sthursfield src gnome org>]

commit 7779f200deff0e23bc03a411f786c3ec8adeb7d6
Author: Sam Thursfield <sam afuera me uk>
Date:   Sun Apr 14 16:41:04 2019 +0200

    Improve Uncrustify configuration
    
    This adds a utils/run-uncrustify.sh script, which can be used to fix
    the indentation of the Tracker source code while ignoring certain files
    (copied in from other projects) which don't match the normal style.
    
    The uncrustify configuration is improved, but there are still at least
    two major issues that make it unusuable:
    
      * Aligning of variable definitions in function bodies is somewhat
        random and I don't yet understand how the relevant configuration
        options are supposed to work.
    
      * struct initializers (specificially GOptionEntry structs) are
        uglified, by moving the closing '}' character onto the same line
        as the last struct value. We actually want a newline here and I
        haven't yet found an option in Uncrustify to enable this behaviour.
    
    See also: https://gitlab.gnome.org/GNOME/tracker/issues/90

 utils/run-uncrustify.sh |  24 ++++++++++
 utils/uncrustify.cfg    | 115 ++++++++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 136 insertions(+), 3 deletions(-)
---
diff --git a/utils/run-uncrustify.sh b/utils/run-uncrustify.sh
new file mode 100755
index 000000000..100c02943
--- /dev/null
+++ b/utils/run-uncrustify.sh
@@ -0,0 +1,24 @@
+#!/bin/bash
+
+# Adapted from Nautilus:
+# https://gitlab.gnome.org/GNOME/nautilus/blob/master/data/run-uncrustify.sh
+
+DATA=$(dirname "$BASH_SOURCE")
+UNCRUSTIFY=$(command -v uncrustify)
+
+if [ -z "$UNCRUSTIFY" ];
+then
+    echo "Uncrustify is not installed on your system."
+    exit 1
+fi
+
+for DIR in {src/libtracker-*,src/tracker,src/tracker-store}
+do
+    for FILE in $(find "$DIR" -name "*.c")
+    do
+       if [ "$FILE" != "src/libtracker-fts/fts5.c" ]; then
+            "$UNCRUSTIFY" -c "./utils/uncrustify.cfg" --no-backup "$FILE"
+       fi
+   done
+done
+
diff --git a/utils/uncrustify.cfg b/utils/uncrustify.cfg
index 433c6999a..cdcae4fc0 100644
--- a/utils/uncrustify.cfg
+++ b/utils/uncrustify.cfg
@@ -1,13 +1,122 @@
 # Configuration for formatting Tracker source code using the
 # 'uncrustify' indent tool.
+#
+# Run `uncrustify --show-config` to see documentation for these options.
+#
+# See also: https://wiki.gnome.org/Projects/Tracker/Documentation/CodingStyle
 
+#################################################################################
+# CHANGES
+#
+# The first part of this file controls what automated changes Uncrustify makes.
+#################################################################################
+
+# We use tabs to indent up to brace level, but spaces to align continuation
+# lines. For example:
+#
+#     int main() {
+#     --->printf ("This is a long string "
+#     --->        "which continues onto a second line.");
+#     };
+#
+align_with_tabs = false
+indent_with_tabs = 1
+
+# We align parameters in function definitions, like this:
+#
+#     gdouble tracker_string_to_date (const gchar *date_string,
+#                                     gint        *offset_p,
+#                                     GError      **error)
+#
 align_func_params = true
 
-align_var_def_star_style = 2
+# A '*' in a variable definition is considered 'dangling', rather than
+# being part of the variable type. This produces the following style of
+# alignment:
+#
+#    tracker_string_to_date (const gchar *date_string,
+#                            gint        *offset_p,
+#                            GError     **error)
+#
+align_var_def_star_style = 2  # dangling
+
+# Keep extra spaces which uncrustify thinks are not needed for alignment.
+#
+# This causes uncrustify to preserve a lot more of the existing alignment
+# in Tracker's source code, for example we can keep this:
+#
+#    tracker_string_to_date (const gchar  *date_string,
+#                            gint         *offset_p,
+#                            GError      **error)
+#
+# Instead of it being changed to this:
+#
+#    tracker_string_to_date (const gchar *date_string,
+#                            gint        *offset_p,
+#                            GError     **error)
+#
+# Because this setting is enabled, the uncrustify process is not
+# idempodent with regards to varable alignment because we still have some
+# extra alignment in the sourcecode which uncrustify did not insert, and
+# rerunning uncrustify with different settings might remove those extra spaces.
+align_keep_extra_space = true
+
+# Align variable definitions in function bodies, at the toplevel, and inside
+# structs.
+#
+# The 'thresh' (threshold) values define the maximum number of extra spaces
+# uncrustify will insert. So align will be done with a maximum of 1 extra
+# space, otherwise the variable will not be aligned with its neighbour.
+align_var_def_thresh = 1
+align_var_struct_thresh = 1
+
+# The 'span' values define how many lines uncrustify will 'jump' in order to
+# consider two variable definitions as neighbours.
+align_var_def_span = 1
+align_var_struct_span = 4
+
+
+#################################################################################
+# IGNORES
+#
+# The second part of this file controls what Uncrustify ignores.
+#################################################################################
 
-sp_after_ptr_star = remove
+# Disable auto-alignment of macros, we manually align the \ with
+# spaces which uncrustify doesn't support.
+align_nl_cont = false
 
+# Ignore spacing multiline comments.
+cmt_indent_multi = false
+
+# Ignore spacing around = operator (and -=, etc).
+sp_after_assign = ignore
+sp_before_assign = ignore
+
+# Ignore space after casts like `(int)foo`
+sp_after_cast = ignore
+
+# Ignore spacing around pointer stars.
+sp_after_ptr_star = ignore
+
+# Ignore spaces after ; in for (; ; ;) statements.
 sp_after_semi_for = ignore
 sp_after_semi_for_empty = ignore
 
-align_nl_cont = true
+# Ignore spacing around ++ / -- operators.
+sp_incdec = ignore
+
+# Ignore Space after ! (not) operator, for example:
+#
+#     if (!home) {
+#
+sp_not = ignore
+
+# Ignore space around preprocessor '##' operator. We might want a space before
+# and no space after, for example in this:
+#
+#     #define trace(message, ...) \
+#         g_debug (message, ##__VA_ARGS__)
+#
+sp_pp_concat = ignore
+