[clang-format] Add new option PenaltyIndentedWhitespace

[mnauw]

Summary

As the example in the comment within the patch shows, the intention of yet-another-penalty is to discourage some "far-right-cascading" indentation cases. Of course, mileage and taste may vary, so the default does not affect current behavior in any way. Likewise, the option may well be named otherwise (etc).

I realize the patch is likely incomplete (and requires additional test and documentation changes), but it would first have to be considered useful and acceptable in the first place.

[MyDeveloperDay]

1. This requires unit tests
2. This requires a fill context diff
3. This requires changes to the ClangFormatStyleOptions.rst by running the dump_style tool in clang/docs/tools

[mnauw]

Patch updated to include unit test and documentation changes (and to use full diff).

[MyDeveloperDay]

LGTM

[mnauw]

Thanks. However, I do not have commit access, so someone may have to arrange for that ...

clang/include/clang/Format/Format.h

   /// line.
   unsigned PenaltyReturnTypeOnItsOwnLine;
 
+  /// Penalty for whitespace indentation
+  unsigned PenaltyIndentedWhitespace;
+
   /// The ``&`` and ``*`` alignment style.
   enum PointerAlignmentStyle {
     /// Align pointer to the left.

clang/lib/Format/ContinuationIndenter.cpp

 
   State.Column = getNewLineColumn(State);
 
+  // Add Penalty proportional to amount of whitespace away from FirstColumn
+  // This tends to penalize several lines that are far-right indented,
+  // and prefers a line-break prior to such a block, e.g:
+  //
+  // Constructor() :
+  //   member(value), looooooooooooooooong_member(
+  //                      looooooooooong_call(param_1, param_2, param_3))
+  // would then become
+  // Constructor() :
+  //   member(value),
+  //   looooooooooooooooong_member(
+  //       looooooooooong_call(param_1, param_2, param_3))
+  if (State.Column > State.FirstIndent)
+    Penalty +=
+        Style.PenaltyIndentedWhitespace * (State.Column - State.FirstIndent);
+
   // Indent nested blocks relative to this column, unless in a very specific
   // JavaScript special case where:
   //

clang/lib/Format/Format.cpp

     IO.mapOptional("PenaltyExcessCharacter", Style.PenaltyExcessCharacter);
     IO.mapOptional("PenaltyReturnTypeOnItsOwnLine",
                    Style.PenaltyReturnTypeOnItsOwnLine);
+    IO.mapOptional("PenaltyIndentedWhitespace",
+                   Style.PenaltyIndentedWhitespace);
     IO.mapOptional("PointerAlignment", Style.PointerAlignment);
     IO.mapOptional("RawStringFormats", Style.RawStringFormats);
     IO.mapOptional("ReflowComments", Style.ReflowComments);

   LLVMStyle.PenaltyReturnTypeOnItsOwnLine = 60;
   LLVMStyle.PenaltyBreakBeforeFirstCallParameter = 19;
   LLVMStyle.PenaltyBreakTemplateDeclaration = prec::Relational;
+  LLVMStyle.PenaltyIndentedWhitespace = 0;
 
   LLVMStyle.DisableFormat = false;
   LLVMStyle.SortIncludes = true;