Investigate clang-format limitations

[gilles-peskine-arm]

Some clang-format limitations seen in #4887 for the coding style change:

• Only modifies whitespace, can't e.g. remove parentheses around return values, or add/remove braces.
  • We have an ad hoc script to remove parentheses around return values.
• Breaks alignment in places where it's nice to have (e.g. series of #define NAME value with aligned values), and apparently can't be told not to.

This is a time-bounded task (a couple of days tops) to investigate those limitations: can we use another tool in combination, or configure the tool differently?

[gilles-peskine-arm]

Note that we may want to combine clang-format with clang-tidy. Clang-tidy can make corrections for some issues, like requiring braces around statements.

[gilles-peskine-arm]

Note that we may want to combine clang-format with clang-tidy.

A major limitation of clang-tidy is that it can only operate on a file which can be compiled as C. In our code base, this excludes:

• Several headers that can only included inside specific other headers. There are circular dependencies between type definitions that are defined in different source files, e.g. between include/psa/crypto_struct.h and include/psa/crypto_builtin_composites.h, or between include/mbedtls/ecp.h and tests/include/alt-dummy/ecp_alt.h. Solvable, but only in an annoying way. We can skip those files — what we're planning to use clang-tidy for is mostly not present in headers anyway.
• Templates (tests_suites/helpers.function, tests_suites/host_test.function, tests_suites/main_test.function, scripts/data_files/*.fmt). Probably solvable by tweaking the templating (except for Jinja templates).
• Most test suites tests/suites/test_suites_*.function. This one's annoying because it's littered with goto exit statements with no exit label (when there's no cleanup, the test framework adds an exit label).
• programs/ssl/ssl_test_common_source.c, which needs a different definition of opt for its two enclosing files. A clumsy but effective workaround is to define opt specially when running clang-tidy.

If we run clang-tidy, I don't see a convenient way to run it on the test suites, unless we're prepared to add exit: ; to all the test functions that don't have cleanup code.

[gilles-peskine-arm]

Having compared uncrustify and clang-format, we're going with uncrustify. It's more fiddly, but on the redeeming side it's more powerful. Clang-format might be ok for checking, but it's insufficient for rewriting the current style, because we want to rearrange braces and parentheses. Clang-tidy can add braces but doesn't run on code that doesn't compile such as .function files. Clang-format is too strict sometimes, in particular in code that we want to keep aligned, which uncrustify can do.