[tracker/wip/carlosg/code-style-checks: 1/4] Improve Uncrustify configuration

[Carlos Garnacho <carlosg src gnome org>]

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

    Improve Uncrustify configuration
    
    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/uncrustify.cfg | 115 +++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 112 insertions(+), 3 deletions(-)
---
diff --git a/utils/uncrustify.cfg b/utils/uncrustify.cfg
index 433c6999a..deddbc6b4 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 variable 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
+