Merge pull request #1930 from manavgabhawala/master

[CHANGELOG][Docs] Update CHANGELOG and Docs to reflect new parsing of function parameter attributes like 'var', 'let' and 'inout' for SE-0003, SE-0031 and SE-0053

Author: tkremenek

CHANGELOG.md

@@ -3,6 +3,31 @@ Note: This is in reverse chronological order, so newer entries are added to the
 Swift 3.0
 -------
 
+* [SE-0031](https://github.com/apple/swift-evolution/blob/master/proposals/0031-adjusting-inout-declarations.md) The location of the inout attribtue has been moved to after the `:` and before the parameter type.
+```swift
+  func foo(inout x: Int) {
+  }
+```
+  will now be written as:
+```swift
+  func foo(x: inout Int) {
+  }
+```
+
+* [SE-0053](https://github.com/apple/swift-evolution/blob/master/proposals/0053-remove-let-from-function-parameters.md) `let` is no longer accepted as a parameter attribute for functions. The compiler provides a fixit to remove it from the function declaration.
+
+* [SE-0003](https://github.com/apple/swift-evolution/blob/master/proposals/0003-remove-var-parameters.md) `var` is no longer accepted as a parameter attribute for functions. The compiler provides a fixit to create a shadow copy in the function body.
+```swift
+  func foo(var x: Int) {
+  }
+```
+  will now be written as:
+```swift
+  func foo(x: Int) {
+    var x = x
+  }
+```
+
 * The "none" members of imported NS_OPTIONS option sets are marked as unavailable
   when they are imported.  Use [] to make an empty option set, instead of a None member.
 

docs/MutationModel.rst

@@ -252,7 +252,7 @@ unless the method is attributed with ``mutating``:
 
 .. parsed-literal::
 
-  func f(x: Int, inout y: Int) {
+  func f(x: Int, y: inout Int) {
     y = x         // ok, y is an inout parameter
     x = y         // **Error:** function parameter 'x' is immutable
   }

docs/OptimizationTips.rst

@@ -253,7 +253,7 @@ through the usage of ``inout`` parameters:
 
 ::
 
-  func append_one_in_place(inout a: [Int]) {
+  func append_one_in_place(a: inout [Int]) {
     a.append(1)
   }
 

docs/SIL.rst

@@ -315,8 +315,8 @@ has the following lowered type::
   @callee_owned () -> @owned @callee_owned (@in (Int,Int)) -> @out Float.
 
 As another example, suppose that ``h`` has type
-``Generator<(Int, @inout Int) -> Float>``.  Neither ``(Int, @inout Int)``
-nor ``@inout Int`` are potential results of substitution because they
+``Generator<(Int, inout Int) -> Float>``.  Neither ``(Int, inout Int)``
+nor ``inout Int`` are potential results of substitution because they
 aren't materializable, so ``h.fn`` has the following lowered type::
 
   @callee_owned () -> @owned @callee_owned (@in Int, @inout Int) -> @out Float
@@ -1447,7 +1447,7 @@ getter prior to calling the function and to write back to the property
 on return by loading from the buffer and invoking the setter with the final
 value. This Swift function::
 
-  func inout(x:@inout Int) {
+  func inout(x: inout Int) {
     x = 1
   }
 

docs/StdlibAPIGuidelines.rst

@@ -183,7 +183,7 @@ Acceptable Short or Non-Descriptive Names
 
   .. parsed-literal::
 
-    func swap<**T**>(inout lhs: T, inout rhs: T)
+    func swap<**T**>(lhs: inout T, rhs: inout T)
 
 * `lhs` and `rhs` are acceptable names for binary operator or
   symmetric binary function parameters:
@@ -192,7 +192,7 @@ Acceptable Short or Non-Descriptive Names
 
     func + (**lhs**: Int, **rhs**: Int) -> Int
 
-    func swap<T>(inout **lhs**: T, inout **rhs**: T)
+    func swap<T>(**lhs**: inout T, **rhs**: inout T)
 
 * `body` is an acceptable name for a trailing closure argument when
   the resulting construct is supposed to act like a language extension

docs/archive/LangRef.html

@@ -803,7 +803,7 @@ <h4 id="attribute-inout"><tt>inout</tt> Attribute</h4>
     For example, the following code:
 
   <pre class=example>
-    func foo(inout x: Int) -> () -> Int {
+    func foo(x: inout Int) -> () -> Int {
       func bar() -> Int {
         x += 1
         return x

docs/proposals/Accessors.rst

@@ -434,7 +434,7 @@ completing the operation.  This can present the opportunity for
 corruption if the interleaved code modifies the original value.
 Consider the following code::
 
-  func operate(inout value: Int, count: Int) { ... }
+  func operate(value: inout Int, count: Int) { ... }
 
   var array: [Int] = [1,2,3,4]
   operate(&array[0], { array = []; return 0 }())
@@ -454,7 +454,7 @@ Nor can this be fixed with a purely local analysis; consider::
   class C { var array: [Int] }
   let global_C = C()
 
-  func assign(inout value: Int) {
+  func assign(value: inout Int) {
     C.array = []
     value = 0
   }
@@ -706,7 +706,7 @@ that was technically copied beforehand.  For example::
   // This function copies array before modifying it, but because that
   // copy is of a value undergoing modification, the copy will use
   // the same buffer and therefore observe updates to the element.
-  func foo(inout element: Int) {
+  func foo(element: inout Int) {
     oldArray = array
     element = 4
   }
@@ -781,7 +781,7 @@ depend on how the l-value is used:
 
   Example::
 
-    func swap<T>(inout lhs: T, inout rhs: T) {}
+    func swap<T>(lhs: inout T, rhs: inout T) {}
 
     // object is a variable of class type
     swap(&leftObject.array, &rightObject.array)

docs/proposals/CPointerArgumentInterop.rst

@@ -316,15 +316,15 @@ An example of a conformance for ``ObjCInOut``::
     typealias WritebackType = Builtin.RawPointer
 
     @_transparent
-    static func _createWriteback(inout ref: T!)
+    static func _createWriteback(ref: inout T!)
     -> Builtin.RawPointer {
       // The initial object reference is passed into the callee effectively
       // __unsafe_unretained, so pass it as a RawPointer.
       return unsafeBitCast(ref, Builtin.RawPointer.self)
     }
 
     @_transparent
-    static func _commitWriteback(inout ref: T!,
+    static func _commitWriteback(ref: inout T!,
                                  value: Builtin.RawPointer) {
       // The reference is autoreleased on return from the caller, so retain it
       // by loading it back as a T?.

docs/proposals/Inplace.rst

@@ -92,7 +92,7 @@ We see at least four problems with this kind of API:
    mutating version of ``op(x: T, y: U) -> T`` can always be defined
    as ::
 
-     func opInPlace(inout x: T, y: U) {
+     func opInPlace(x: inout T, y: U) {
        x = op(x, y)
      }
 
@@ -361,15 +361,15 @@ An assignment operator for an immutable class ``X`` always has the form:
 
 .. parsed-literal::
 
-  func *op*\ **=** (**inout** lhs: X, rhs: Y) {
+  func *op*\ **=** (lhs: **inout** X, rhs: Y) {
     lhs = *expression creating a new X object*
   }
 
 or, with COW optimization:
 
 .. parsed-literal::
 
-  func *op*\ **=** (**inout** lhs: X, rhs: Y) {
+  func *op*\ **=** (lhs: **inout** X, rhs: Y) {
     if isUniquelyReferenced(&lhs) {
       lhs.\ *mutateInPlace*\ (rhs)
     }

docs/proposals/OptimizerEffects.rst

@@ -400,7 +400,7 @@ Example:::
 
 When the optimizer optimizes a loop:::
 
-  func memset(inout A: [Int], value: Int) {
+  func memset(A: inout [Int], value: Int) {
     for i in 0 .. A.size {
       A[i] = value
       f()
@@ -409,7 +409,7 @@ When the optimizer optimizes a loop:::
 
 It will see the following calls because methods with attributes are not inlined.::
 
-  func memset(inout A: [Int], value: Int) {
+  func memset(A: inout [Int], value: Int) {
     for i in 0 .. A.size {
       makeUnique(&A)
       addr = getElementAddr(i, &A)
@@ -768,7 +768,8 @@ after the mutating function. This lets the second ``getElement`` function get
 another array parameter which prevents CSE of the two ``getElement`` calls.
 Shown in this swift-SIL pseudo code::
 
-    func add(var arr: Array<Int>, i: Int) -> Int {
+    func add(arr: Array<Int>, i: Int) -> Int {
+      var arr = arr
       let e1 = getElement(i, arr)
       store arr to stack_array
       setElement(i, 0, &stack_array)
@@ -782,7 +783,8 @@ which directly access the storage, are not inlined during high-level SIL.
 Optimizations like code motion could move a store to the storage over a
 ``readnone getElement``.::
 
-    func add(var arr: Array<Int>, i: Int) -> Int {
+    func add(arr: Array<Int>, i: Int) -> Int {
+      var arr = arr
       let e1 = getElement(i, arr)
       store arr to stack_array
       stack_array.storage[i] = 0          // (1)

docs/proposals/OptionSets.rst

@@ -99,15 +99,15 @@ protocol::
   protocol OptionSet : Equatable {
     // Set intersection
     @infix func &(_:Self, _:Self) -> Self
-    @infix func &=(@inout _:Self, _:Self)
+    @infix func &=(_: inout Self, _:Self)
 
     // Set union
     @infix func |(_:Self, _:Self) -> Self
-    @infix func |=(@inout _:Self, _:Self)
+    @infix func |=(_: inout Self, _:Self)
 
     // Set xor
     @infix func ^(_:Self, _:Self) -> Self
-    @infix func ^=(@inout _:Self, _:Self)
+    @infix func ^=(_: inout Self, _:Self)
 
     // Set negation
     @prefix func ~(_:Self) -> Self

docs/proposals/ValueSemantics.rst

@@ -234,7 +234,7 @@ clonable classes:
  func cycle_length<State>(
    s : State, 
    **next : (x : State) -> State,**
-   **equal : ([inout] x : State, [inout] y : State) -> Bool**
+   **equal : (x : [inout] State, y : [inout] State) -> Bool**
  ) -> Int
    requires State : EqualityComparable
  {

docs/proposals/archive/UnifiedFunctionSyntax.rst

@@ -193,7 +193,7 @@ Swift method name for that Objective-C API. For example, by default,
 the ``NSURL`` method ``+bookmarkDataWithContentsOfURL:error:`` will
 come into Swift as::
 
-  class func bookmarkDataWithContents(ofURL bookmarkFileURL: NSURL, inout error: NSError) -> NSData
+  class func bookmarkDataWithContents(ofURL bookmarkFileURL: NSURL, error: inout NSError) -> NSData
 
 However, one can provide a different mapping with the ``method_name``
 attribute::