Skip to content

Commit

Permalink
[Alamofire 5]: Update all inline API documentation. (Alamofire#2845)
Browse files Browse the repository at this point in the history 
* Rename internal Result extensions.

* Update Alamofire docs.

* Update AFError docs.

* Cleanup HTTPHeaders.

* ParameterEncoder doc update.

* Whitespace cleanup.

* Update all Request docs, update Destination and cancel handling.

* Refactor download cancellation for common method.

* Start Session documentation.

* Update Gems.

* Update Session queue ids.

* Continue Session docs.

* DataRequest and DownloadRequest docs.

* Add default value note.

* Continue request docs.

* Whitespace cleanup.

* Finish Session docs, update AF docs.

* Small doc cleanup.

* SessionDelegate cleanup.

* Update docs for NetworkReachabilityManager.

* Update docs for MultipartFormData.

* Remove OS check, as compiler warns.

* Update RedirectHandler docs.

* Update RequestInterceptor docs.

* Update ServerTrustEvaluation docs.

* ResponseSerialization doc updates.

* Misc. cleanup.

* Update Gems.

* Add docs for missed public API.

* Make cancel() on DownloadRequest not produce resumeData.

* Fix download events.

* Add missing fileManager parameter.

* Make event tests more explicit.

* Whitespace cleanup.

* ParameterEncoding -> ParameterEncoder

* Fix typo.

* Updates for PR feedback.

* Final PR fixes.

* Add extra line before Returns doc.

* Clean up download cancellation.
  • Loading branch information
@jshier
jshier committed Jun 29, 2019
1 parent 1b89a57 commit dfd0ac2
Show file tree
Hide file tree
Showing 33 changed files with 1,644 additions and 655 deletions.
2 changes: 1 addition & 1 deletion Gemfile
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
source "https://rubygems.org"

gem "cocoapods", "~> 1.6"
gem "cocoapods"
gem "xcpretty"
gem "jazzy"
34 changes: 17 additions & 17 deletions Gemfile.lock
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,11 +9,11 @@ GEM
tzinfo (~> 1.1)
atomos (0.1.3)
claide (1.0.2)
cocoapods (1.6.1)
cocoapods (1.7.2)
activesupport (>= 4.0.2, < 5)
claide (>= 1.0.2, < 2.0)
cocoapods-core (= 1.6.1)
cocoapods-deintegrate (>= 1.0.2, < 2.0)
cocoapods-core (= 1.7.2)
cocoapods-deintegrate (>= 1.0.3, < 2.0)
cocoapods-downloader (>= 1.2.2, < 2.0)
cocoapods-plugins (>= 1.0.0, < 2.0)
cocoapods-search (>= 1.0.0, < 2.0)
Expand All @@ -22,13 +22,13 @@ GEM
cocoapods-try (>= 1.1.0, < 2.0)
colored2 (~> 3.1)
escape (~> 0.0.4)
fourflusher (>= 2.2.0, < 3.0)
fourflusher (>= 2.3.0, < 3.0)
gh_inspector (~> 1.0)
molinillo (~> 0.6.6)
nap (~> 1.0)
ruby-macho (~> 1.4)
xcodeproj (>= 1.8.1, < 2.0)
cocoapods-core (1.6.1)
xcodeproj (>= 1.10.0, < 2.0)
cocoapods-core (1.7.2)
activesupport (>= 4.0.2, < 6)
fuzzy_match (~> 2.0.4)
nap (~> 1.0)
Expand All @@ -45,25 +45,25 @@ GEM
colored2 (3.1.2)
concurrent-ruby (1.1.5)
escape (0.0.4)
ffi (1.10.0)
fourflusher (2.2.0)
ffi (1.11.1)
fourflusher (2.3.1)
fuzzy_match (2.0.4)
gh_inspector (1.1.3)
i18n (0.9.5)
concurrent-ruby (~> 1.0)
jazzy (0.9.4)
cocoapods (~> 1.0)
mustache (~> 0.99)
jazzy (0.10.0)
cocoapods (~> 1.5)
mustache (~> 1.1)
open4
redcarpet (~> 3.2)
redcarpet (~> 3.4)
rouge (>= 2.0.6, < 4.0)
sass (~> 3.4)
sass (~> 3.6)
sqlite3 (~> 1.3)
xcinvoke (~> 0.3.0)
liferaft (0.0.6)
minitest (5.11.3)
molinillo (0.6.6)
mustache (0.99.8)
mustache (1.1.0)
nanaimo (0.2.6)
nap (1.1.0)
netrc (0.11.0)
Expand All @@ -79,13 +79,13 @@ GEM
sass-listen (4.0.0)
rb-fsevent (~> 0.9, >= 0.9.4)
rb-inotify (~> 0.9, >= 0.9.7)
sqlite3 (1.4.0)
sqlite3 (1.4.1)
thread_safe (0.3.6)
tzinfo (1.2.5)
thread_safe (~> 0.1)
xcinvoke (0.3.0)
liferaft (~> 0.0.6)
xcodeproj (1.8.2)
xcodeproj (1.10.0)
CFPropertyList (>= 2.3.3, < 4.0)
atomos (~> 0.1.3)
claide (>= 1.0.2, < 2.0)
Expand All @@ -98,7 +98,7 @@ PLATFORMS
ruby

DEPENDENCIES
cocoapods (~> 1.6)
cocoapods
jazzy
xcpretty

Expand Down
97 changes: 41 additions & 56 deletions Source/AFError.swift
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,29 +26,16 @@ import Foundation

/// `AFError` is the error type returned by Alamofire. It encompasses a few different types of errors, each with
/// their own associated reasons.
///
/// - explicitlyCancelled: Returned when a `Request` is explicitly cancelled.
/// - invalidURL: Returned when a `URLConvertible` type fails to create a valid `URL`.
/// - parameterEncodingFailed: Returned when a parameter encoding object throws an error during the encoding process.
/// - parameterEncoderFailed: Returned when a parameter encoder throws an error during the encoding process.
/// - multipartEncodingFailed: Returned when some step in the multipart encoding process fails.
/// - requestAdaptationFailed: Returned when a `RequestAdapter` throws an error during request adaptation.
/// - responseValidationFailed: Returned when a `validate()` call fails.
/// - responseSerializationFailed: Returned when a response serializer throws an error in the serialization process.
/// - serverTrustEvaluationFailed: Returned when a `ServerTrustEvaluating` instance fails during the server trust evaluation process.
/// - requestRetryFailed: Returned when a `RequestRetrier` throws an error during the request retry process.
public enum AFError: Error {
/// The underlying reason the parameter encoding error occurred.
///
/// - missingURL: The URL request did not have a URL to encode.
/// - jsonEncodingFailed: JSON serialization failed with an underlying system error during the
/// encoding process.
/// The underlying reason the `.parameterEncodingFailed` error occurred.
public enum ParameterEncodingFailureReason {
/// The `URLRequest` did not have a `URL` to encode.
case missingURL
/// JSON serialization failed with an underlying system error during the encoding process.
case jsonEncodingFailed(error: Error)
}

/// Underlying reason the parameter encoder error occured.
/// The underlying reason the `.parameterEncoderFailed` error occured.
public enum ParameterEncoderFailureReason {
/// Possible missing components.
public enum RequiredComponent {
Expand All @@ -63,63 +50,48 @@ public enum AFError: Error {
case encoderFailed(error: Error)
}

/// The underlying reason the multipart encoding error occurred.
///
/// - bodyPartURLInvalid: The `fileURL` provided for reading an encodable body part isn't a
/// file URL.
/// - bodyPartFilenameInvalid: The filename of the `fileURL` provided has either an empty
/// `lastPathComponent` or `pathExtension.
/// - bodyPartFileNotReachable: The file at the `fileURL` provided was not reachable.
/// - bodyPartFileNotReachableWithError: Attempting to check the reachability of the `fileURL` provided threw
/// an error.
/// - bodyPartFileIsDirectory: The file at the `fileURL` provided is actually a directory.
/// - bodyPartFileSizeNotAvailable: The size of the file at the `fileURL` provided was not returned by
/// the system.
/// - bodyPartFileSizeQueryFailedWithError: The attempt to find the size of the file at the `fileURL` provided
/// threw an error.
/// - bodyPartInputStreamCreationFailed: An `InputStream` could not be created for the provided `fileURL`.
/// - outputStreamCreationFailed: An `OutputStream` could not be created when attempting to write the
/// encoded data to disk.
/// - outputStreamFileAlreadyExists: The encoded body data could not be writtent disk because a file
/// already exists at the provided `fileURL`.
/// - outputStreamURLInvalid: The `fileURL` provided for writing the encoded body data to disk is
/// not a file URL.
/// - outputStreamWriteFailed: The attempt to write the encoded body data to disk failed with an
/// underlying error.
/// - inputStreamReadFailed: The attempt to read an encoded body part `InputStream` failed with
/// underlying system error.
/// The underlying reason the `.multipartEncodingFailed` error occurred.
public enum MultipartEncodingFailureReason {
/// The `fileURL` provided for reading an encodable body part isn't a file `URL`.
case bodyPartURLInvalid(url: URL)
/// The filename of the `fileURL` provided has either an empty `lastPathComponent` or `pathExtension.
case bodyPartFilenameInvalid(in: URL)
/// The file at the `fileURL` provided was not reachable.
case bodyPartFileNotReachable(at: URL)
/// Attempting to check the reachability of the `fileURL` provided threw an error.
case bodyPartFileNotReachableWithError(atURL: URL, error: Error)
/// The file at the `fileURL` provided is actually a directory.
case bodyPartFileIsDirectory(at: URL)
/// The size of the file at the `fileURL` provided was not returned by the system.
case bodyPartFileSizeNotAvailable(at: URL)
/// The attempt to find the size of the file at the `fileURL` provided threw an error.
case bodyPartFileSizeQueryFailedWithError(forURL: URL, error: Error)
/// An `InputStream` could not be created for the provided `fileURL`.
case bodyPartInputStreamCreationFailed(for: URL)

/// An `OutputStream` could not be created when attempting to write the encoded data to disk.
case outputStreamCreationFailed(for: URL)
/// The encoded body data could not be written to disk because a file already exists at the provided `fileURL`.
case outputStreamFileAlreadyExists(at: URL)
/// The `fileURL` provided for writing the encoded body data to disk is not a file `URL`.
case outputStreamURLInvalid(url: URL)
/// The attempt to write the encoded body data to disk failed with an underlying error.
case outputStreamWriteFailed(error: Error)

/// The attempt to read an encoded body part `InputStream` failed with underlying system error.
case inputStreamReadFailed(error: Error)
}

/// The underlying reason the response validation error occurred.
///
/// - dataFileNil: The data file containing the server response did not exist.
/// - dataFileReadFailed: The data file containing the server response could not be read.
/// - missingContentType: The response did not contain a `Content-Type` and the `acceptableContentTypes`
/// provided did not contain wildcard type.
/// - unacceptableContentType: The response `Content-Type` did not match any type in the provided
/// `acceptableContentTypes`.
/// - unacceptableStatusCode: The response status code was not acceptable.
/// The underlying reason the `.responseValidationFailed` error occurred.
public enum ResponseValidationFailureReason {
/// The data file containing the server response did not exist.
case dataFileNil
/// The data file containing the server response at the associated `URL` could not be read.
case dataFileReadFailed(at: URL)
/// The response did not contain a `Content-Type` and the `acceptableContentTypes` provided did not contain a
/// wildcard type.
case missingContentType(acceptableContentTypes: [String])
/// The response `Content-Type` did not match any type in the provided `acceptableContentTypes`.
case unacceptableContentType(acceptableContentTypes: [String], responseContentType: String)
/// The response status code was not acceptable.
case unacceptableStatusCode(code: Int)
}

Expand Down Expand Up @@ -164,6 +136,7 @@ public enum AFError: Error {
self.result = result
}
}
/// No `ServerTrustEvaluator` was found for the associated host.
case noRequiredEvaluator(host: String)
/// No certificates were found with which to perform the trust evaluation.
case noCertificatesFound
Expand All @@ -187,17 +160,29 @@ public enum AFError: Error {
case publicKeyPinningFailed(host: String, trust: SecTrust, pinnedKeys: [SecKey], serverKeys: [SecKey])
}

/// `Session` which issued the `Request` was deinitialized, most likely because its reference went out of scope.
case sessionDeinitialized
/// `Session` was explicitly invalidated, possibly with the `Error` produced by the underlying `URLSession`.
case sessionInvalidated(error: Error?)
/// `Request` was explcitly cancelled.
case explicitlyCancelled
/// `URLConvertible` type failed to create a valid `URL`.
case invalidURL(url: URLConvertible)
/// `ParameterEncoding` threw an error during the encoding process.
case parameterEncodingFailed(reason: ParameterEncodingFailureReason)
/// `ParameterEncoder` threw an error while running the encoder.
case parameterEncoderFailed(reason: ParameterEncoderFailureReason)
/// Multipart form encoding failed.
case multipartEncodingFailed(reason: MultipartEncodingFailureReason)
/// `RequestAdapter` failed threw an error during adaptation.
case requestAdaptationFailed(error: Error)
/// Response validation failed.
case responseValidationFailed(reason: ResponseValidationFailureReason)
/// Response serialization failued.
case responseSerializationFailed(reason: ResponseSerializationFailureReason)
/// `ServerTrustEvaluating` instance threw an error during trust evaluation.
case serverTrustEvaluationFailed(reason: ServerTrustFailureReason)
/// `RequestRetrier` threw an error during the request retry process.
case requestRetryFailed(retryError: Error, originalError: Error)
}

Expand All @@ -211,13 +196,13 @@ extension Error {
// MARK: - Error Booleans

extension AFError {
// Returns whether the instance is `.sessionDeinitialized`.
/// Returns whether the instance is `.sessionDeinitialized`.
public var isSessionDeinitializedError: Bool {
if case .sessionDeinitialized = self { return true }
return false
}

// Returns whether the instance is `.sessionInvalidated`.
/// Returns whether the instance is `.sessionInvalidated`.
public var isSessionInvalidatedError: Bool {
if case .sessionInvalidated = self { return true }
return false
Expand All @@ -243,7 +228,7 @@ extension AFError {
}

/// Returns whether the instance is `.parameterEncoderFailed`. When `true`, the `underlyingError` property will
// contain the associated value.
/// contain the associated value.
public var isParameterEncoderError: Bool {
if case .parameterEncoderFailed = self { return true }
return false
Expand Down
7 changes: 3 additions & 4 deletions Source/AFResult.swift
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,21 +22,20 @@
// THE SOFTWARE.
//

import Foundation

/// `Result` that always has an `Error` `Failure` type.
public typealias AFResult<T> = Result<T, Error>

// MARK: - Internal APIs

extension AFResult {
/// Returns the associated value if the result is a success, `nil` otherwise.
var value: Success? {
var success: Success? {
guard case .success(let value) = self else { return nil }
return value
}

/// Returns the associated error value if the result is a failure, `nil` otherwise.
var error: Failure? {
var failure: Failure? {
guard case .failure(let error) = self else { return nil }
return error
}
Expand Down
Loading

0 comments on commit dfd0ac2

Please sign in to comment.