Mark aliases onError and errorValue as deprecated

And include more documentation on their use.

Author: nathanhosselton

Sources/Promise+Properties.swift

@@ -14,9 +14,20 @@ extension Promise {
     }
 
     /**
-     - Returns: The error with which this promise was rejected; `nil` if this promise is not rejected.
-       Alternative for the cases where the Swift compiler gets confused over the name of the `error` property
+     Provides an alias for the `error` property for cases where the Swift
+     compiler cannot disambiguate from our `error` function.
+     
+     More than likely use of this alias will never be necessary as it's
+     the inverse situation where Swift usually becomes confused. But 
+     we provide this anyway just in case.
+     
+     If you absolutely cannot get Swift to accept `error` then 
+     `errorValue` may be used instead as it returns the same thing.
+
+     - Warning: This alias will be unavailable in PromiseKit 4.0.0
+     - SeeAlso: [https://github.com/mxcl/PromiseKit/issues/347](https://github.com/mxcl/PromiseKit/issues/347)
     */
+    @available(*, deprecated, renamed="error", message="Temporary alias `errorValue` will eventually be removed and should only be used when the Swift compiler cannot be satisfied with `error`")
     public var errorValue: ErrorType? {
         return self.error
     }

Sources/Promise.swift

@@ -391,9 +391,28 @@ public class Promise<T> {
     }
 
     /**
-     Provides an alias for the `error` function for cases where the Swift compiler gets into trouble inferring the right
-     types. If `error` does not work, consider using `onError` instead which does the same thing.
+     Provides an alias for the `error` function for cases where the Swift
+     compiler cannot disambiguate from our `error` property. If you're
+     having trouble with `error`, before using this alias, first try 
+     being as explicit as possible with the types e.g.:
+
+         }.error { (error:ErrorType) -> Void in
+             //...
+         }
+
+     Or even using verbose function syntax:
+
+         }.error({ (error:ErrorType) -> Void in
+             //...
+         })
+     
+     If you absolutely cannot get Swift to accept `error` then `onError`
+     may be used instead as it does the same thing.
+     
+     - Warning: This alias will be unavailable in PromiseKit 4.0.0
+     - SeeAlso: [https://github.com/mxcl/PromiseKit/issues/347](https://github.com/mxcl/PromiseKit/issues/347)
     */
+    @available(*, deprecated, renamed="error", message="Temporary alias `onError` will eventually be removed and should only be used when the Swift compiler cannot be satisfied with `error`")
     public func onError(policy policy: ErrorPolicy = .AllErrorsExceptCancellation, _ body: (ErrorType) -> Void) {
         error(policy: policy, body)
     }

Tests/CorePromise/ErrorUnhandler.test.swift

@@ -116,8 +116,7 @@ class ErrorHandlingTests_Swift: XCTestCase {
         }
     }
 
-
-    // an alias called `onError` exists for the `error` function
+    // a temporary alias `onError` exists for the `error` function
     func test7() {
         twice { promise, ex in
             PMKUnhandledErrorHandler = { err in