[SourceKit/CodeFormat] Improve documentation and fix propagation of ContextLocs.

- Rename several symbols to make it clearer whether the ranges they deal with
  are open or closed.
- Add comments documenting the implementation of OutdentChecker::hasOutdent
- Fix a bug where code after a doc coment block of the '/**' style was being
  indented 1 space.
- Fix IsInStringLiteral not being set if the indent target was in a string
  segment of an interpolated multiline string.
- Update OutdentChecker::hasOutdent to propagate indent contexts from
  parent parens/brackets/braces to child parens/brackets/braces that start
  later in the same line (like FormatWalker already does). This changes the
  braces in the example below to 'inherit' a ContextLoc from their parent
  square brackets, which have a ContextLoc at 'foo'. This makes the whole
  expression be correctly considered 'outdenting':

  foo(a: "hello"
      b: "hello")[x: {
    print("hello")
  }]

Author: Nathan Hawes

lib/IDE/Formatting.cpp

@@ -0,0 +1,8 @@
+func foo() {
+    foo { (
+        x, 
+        y
+    ) in
+
+// RUN: %sourcekitd-test -req=format -line=6 -length=1 %s | %FileCheck --strict-whitespace %s
+// CHECK: key.sourcetext: "        "

test/SourceKit/CodeFormat/indent-trailing/trailing-closure-in.swift

@@ -0,0 +1,7 @@
+func foo() {
+    bar
+        .fooooooooooo(first: 3,
+                      second)[x: 10] {
+
+// RUN: %sourcekitd-test -req=format -line=5 -length=1 %s | %FileCheck --strict-whitespace %s
+// CHECK: key.sourcetext: "            "

test/SourceKit/CodeFormat/indent-trailing/trailing-closure.swift

@@ -1,5 +1,5 @@
 class Foo {
-	deinit {
+    deinit {
 
 // RUN: %sourcekitd-test -req=format -line=3 -length=1 %s | %FileCheck --strict-whitespace %s
 // CHECK: key.sourcetext: "        "

test/SourceKit/CodeFormat/indent-trailing/trailing-deinit.swift

@@ -0,0 +1,5 @@
+func foo(x: Bool) {
+    guard let number = patterns.index(where: {
+
+// RUN: %sourcekitd-test -req=format -line=3 -length=1 %s | %FileCheck --strict-whitespace %s
+// CHECK: key.sourcetext: "        "

test/SourceKit/CodeFormat/indent-trailing/trailing-guard-condition.swift

@@ -0,0 +1,6 @@
+let foo = Bar.Stuff(
+    first: path,
+    description: "No \(thing) was found at path \(path)"
+
+// RUN: %sourcekitd-test -req=format -line=4 -length=1 %s | %FileCheck --strict-whitespace %s
+// CHECK: key.sourcetext: ""

test/SourceKit/CodeFormat/indent-trailing/trailing-string-element.swift

@@ -13,4 +13,4 @@ $
 // CHECK: key.sourcetext: "struct $ {"
 // CHECK: key.sourcetext: "    let $: <#Type#>"
 // CHECK: key.sourcetext: "        = foo(\"foo \\($) bar\") {"
-// CHECK: key.sourcetext: "$"
+// CHECK: key.sourcetext: "    $"

test/SourceKit/CodeFormat/rdar_32789463.swift

@@ -115,7 +115,9 @@ if #available(
 
 // Trailing closures, subscript expressions and argument tuples/parens should
 // indent relative to the line containing the start of the last named component
-// of their function, or the function start if their are none.
+// of their function, or the function start if their are none. Any child
+// tuples/parens/brackets should that start after them on the same line should
+// do the same.
 //
 let _ = []
         .map {
@@ -146,6 +148,51 @@ basename
         fatalError()
     }
 
+[foo(a: Int,
+     b: Int)[z: {
+    fatalError()
+}],
+"hello"
+]
+
+[foo(a: Int,
+     b: Int)[z: foo ({
+    fatalError()
+}, {
+    fatalError()
+})],
+"hello"
+]
+
+[foo(a: Int,
+     b: Int) {
+    fatalError()
+} [y: 10,
+   z: foo ({
+    fatalError()
+   }, {
+    fatalError()
+   })],
+"hello"
+]
+
+[foo(a: Int,
+     b: Int) [z: foo ()
+{
+    fatalError()
+})],
+"hello"
+]
+
+[foo(a: Int,
+     b: Int) [z: foo (a: 1,
+                      b: 2)
+{
+    fatalError()
+})],
+"hello"
+]
+
 
 // Closing arg parens shouldn't indent.
 //
@@ -240,6 +287,34 @@ let s = """
             c
     """
 
+
+// Interpolations shouldn't change how multiline strings are handled.
+//
+switch self {
+case .first:
+    return """
+        foo foo foo foo foo foo foo foo foo foo foo foo foo foo foo foo foo foo foo \
+        foo foo foo foo foo foo foo foo foo foo foo foo foo foo foo foo foo foo foo.
+        """
+case .second(let a, let b):
+    return """
+        foo foo foo foo foo foo foo foo foo foo foo foo foo foo foo foo \(bar.bar), \
+        foo foo foo foo foo foo foo foo foo foo foo foo foo foo foo foo \(bar.bar).
+        """
+}
+
+
+// Comments after the last item of a collection should still indent.
+//
+let x = [
+    // hello
+    124,
+    // hello
+    123
+    // hello
+]
+
+
 // Pound directives aren't indentation contexts, though this should probably be
 // configurable.
 //
@@ -717,6 +792,11 @@ let myFunc: () -> (Int,
                    Int)
 
 
+// Tuple types should align on their outer label locs (if present)
+//
+typealias Thing = (_ tmpURL: URL,
+                   _ secondURL: URL) -> (destinationURL: URL, options: Options)
+
 // Type member access shouldn't indent.
 //
 func foo(
@@ -818,11 +898,13 @@ foo.bar() {
     return
 }
 
+
 // Handle invalid for each (missing 'in' location)
 //
 for query: foo
 bar;
 
+
 // Handle custom attributes
 //
 @Custom(foo: 3,
@@ -834,3 +916,17 @@ struct Foo {
     )
     var d: Int = 10
 }
+
+// Ignore postfix expressions when determining context locations.
+//
+return Foo(deferred) {
+    print("hello")
+}++
+
+IncrementedFirst++
+    .foo()++
+    .bar {
+
+    }++
+    .baz()
+