From ece34b1b8b3f67a1244b3af29d2bd18523fcd0fe Mon Sep 17 00:00:00 2001 From: etoledom Date: Thu, 7 Mar 2024 15:09:55 +0100 Subject: [PATCH] Improving docs of main types (#97) * Improving docs of main types --- Sources/Gravatar/Gravatar.docc/Gravatar.md | 2 +- .../Network/CancellableDataTask.swift | 5 +++- .../Network/Services/HTTPClient.swift | 15 +++++++++++ .../Network/Services/ImageDownloader.swift | 25 +++++++++++++++++++ .../Network/Services/ImageService.swift | 11 ++++++++ .../Network/Services/ImageUploader.swift | 13 ++++++++++ .../Network/Services/ProfileService.swift | 12 +++++++++ .../Gravatar/Options/GravatarOptions.swift | 17 +++++++------ .../Gravatar/Options/ImageQueryOptions.swift | 2 +- 9 files changed, 92 insertions(+), 10 deletions(-) diff --git a/Sources/Gravatar/Gravatar.docc/Gravatar.md b/Sources/Gravatar/Gravatar.docc/Gravatar.md index 0a78e50f..84507e41 100644 --- a/Sources/Gravatar/Gravatar.docc/Gravatar.md +++ b/Sources/Gravatar/Gravatar.docc/Gravatar.md @@ -27,7 +27,7 @@ gravatarImageView.gravatar.setImage(email: "user@email.com") ``` For more info check: -- ``GravatarWrapper/setImage(email:placeholder:rating:preferredSize:options:completionHandler:)`` +- ``GravatarWrapper/setImage(email:placeholder:rating:preferredSize:defaultImage:options:completionHandler:)`` ## Featured diff --git a/Sources/Gravatar/Network/CancellableDataTask.swift b/Sources/Gravatar/Network/CancellableDataTask.swift index f72e9ec9..71b166ed 100644 --- a/Sources/Gravatar/Network/CancellableDataTask.swift +++ b/Sources/Gravatar/Network/CancellableDataTask.swift @@ -1,7 +1,10 @@ import Foundation -/// Allows you to cancel the data task. +/// Represents the task of a data downloading process, which can be cancelled while it's running. +/// +/// We offer a default implementation of `CancellableDataTask` for `URLSessionTask` and `Task`. public protocol CancellableDataTask { + /// Cancells a running task. func cancel() } diff --git a/Sources/Gravatar/Network/Services/HTTPClient.swift b/Sources/Gravatar/Network/Services/HTTPClient.swift index 420cf2c5..57c1806a 100644 --- a/Sources/Gravatar/Network/Services/HTTPClient.swift +++ b/Sources/Gravatar/Network/Services/HTTPClient.swift @@ -1,7 +1,22 @@ import Foundation +/// A `HTTPClient` is used to perform basic networking operations. +/// +/// You can provide your own type conforming to this protocol to gain control over all networking operations performed internally by this SDK. +/// For more info, see ``ImageService/init(client:cache:)`` and ``ProfileService/init(client:)``. public protocol HTTPClient { + /// Performs a data request using the information provided, and delivers the result asynchronously. + /// - Parameter request: A URL request object that provides request-specific information such as the URL and cache policy. + /// - Returns: An asynchronously-delivered tuple that contains the URL contents as a Data instance, and a HTTPURLResponse. func fetchData(with request: URLRequest) async throws -> (Data, HTTPURLResponse) + + /// Uploads data to a URL based on the specified URL request and delivers the result asynchronously. + /// - Parameters: + /// - request: A URL request object that provides request-specific information such as the URL and cache policy. + /// - data: The data to be uploaded. + /// - Returns: An asynchronously-delivered instance of the returned HTTPURLResponse. func uploadData(with request: URLRequest, data: Data) async throws -> HTTPURLResponse + + // TODO: document after change. func fetchObject(from path: String) async throws -> T } diff --git a/Sources/Gravatar/Network/Services/ImageDownloader.swift b/Sources/Gravatar/Network/Services/ImageDownloader.swift index 11a2e1fc..8997bd7a 100644 --- a/Sources/Gravatar/Network/Services/ImageDownloader.swift +++ b/Sources/Gravatar/Network/Services/ImageDownloader.swift @@ -3,13 +3,27 @@ import UIKit public typealias ImageDownloadCompletion = (Result) -> Void +/// Represents a type which can be used by Gravatar to fetch images. public protocol ImageDownloader { + /// Fetches a Gravatar user profile image using the user account's email. + /// - Parameters: + /// - email: The user account email + /// - options: The options needed to perform the download. + /// - completionHandler: A closure which is called when the task is completed. + /// - Returns: The task of an image downloading process. func fetchImage( with email: String, options: ImageDownloadOptions, completionHandler: ImageDownloadCompletion? ) -> CancellableDataTask + /// Fetches an image from the given `URL`. + /// - Parameters: + /// - url: The URL from where to download the image. + /// - forceRefresh: Force the image to be downloaded, ignoring the cache. + /// - processingMethod: Method to use for processing the downloaded `Data`. + /// - completionHandler: A closure which is called when the task is completed. + /// - Returns: The task of an image downloading process. func fetchImage( with url: URL, forceRefresh: Bool, @@ -17,11 +31,22 @@ public protocol ImageDownloader { completionHandler: ImageDownloadCompletion? ) -> CancellableDataTask? + /// Fetches a Gravatar user profile image using the user account's email, and delivers the image asynchronously. + /// - Parameters: + /// - email: The user account email + /// - options: The options needed to perform the download. + /// - Returns: An asynchronously-delivered Result type containing the image and its URL. func fetchImage( with email: String, options: ImageDownloadOptions ) async throws -> ImageDownloadResult + /// Fetches an image from the given `URL`, and delivers the image asynchronously. + /// - Parameters: + /// - url: The URL from where to download the image. + /// - forceRefresh: Force the image to be downloaded, ignoring the cache. + /// - processingMethod: Method to use for processing the downloaded `Data`. + /// - Returns: An asynchronously-delivered Result type containing the image and its URL. func fetchImage( with url: URL, forceRefresh: Bool, diff --git a/Sources/Gravatar/Network/Services/ImageService.swift b/Sources/Gravatar/Network/Services/ImageService.swift index 7eee77b7..406c53f5 100644 --- a/Sources/Gravatar/Network/Services/ImageService.swift +++ b/Sources/Gravatar/Network/Services/ImageService.swift @@ -1,9 +1,20 @@ import UIKit +/// A service to perform image-related tasks, such as fetching images by email and uploading images to Gravatar. +/// +/// This is the default type which implements ``ImageDownloader`` and ``ImageUploader``. +/// Unless specified otherwise, `ImageService` will use a `URLSession` based `HTTPClient`, and a in-memory image cache. public struct ImageService { private let client: HTTPClient let imageCache: ImageCaching + /// Creates a new `ImageService` + /// + /// Optionally, you can pass a custom type conforming to ``HTTPClient`` to gain control over networking tasks. + /// Similarly, you can pass a custom type conforming to ``ImageCaching`` to use your custom caching system. + /// - Parameters: + /// - client: A type which will perform basic networking operations. + /// - cache: A type which will perform image caching operations. public init(client: HTTPClient? = nil, cache: ImageCaching? = nil) { self.client = client ?? URLSessionHTTPClient() self.imageCache = cache ?? ImageCache() diff --git a/Sources/Gravatar/Network/Services/ImageUploader.swift b/Sources/Gravatar/Network/Services/ImageUploader.swift index 05f86768..853348d7 100644 --- a/Sources/Gravatar/Network/Services/ImageUploader.swift +++ b/Sources/Gravatar/Network/Services/ImageUploader.swift @@ -1,12 +1,25 @@ import UIKit +/// Represents a type which can be used by Gravatar to upload an image to Gravatar. public protocol ImageUploader { + /// Uploads an image to be used as the user's Gravatar profile image, and returns the `URLResponse` of the network tasks asynchronously. + /// - Parameters: + /// - image: The image to be uploaded. + /// - accountEmail: The user email account. + /// - accountToken: The authentication token for the user. + /// - Returns: An asynchronously-delivered `URLResponse` instance, containing the response of the upload network task. func uploadImage( _ image: UIImage, accountEmail: String, accountToken: String ) async throws -> URLResponse + /// Uploads an image to be used as the user's Gravatar profile image. + /// - Parameters: + /// - image: The image to be uploaded. + /// - accountEmail: The user email account. + /// - accountToken: The authentication token for the user. + /// - completion: A closure which will be called when the upload network task finishes. func uploadImage( _ image: UIImage, accountEmail: String, diff --git a/Sources/Gravatar/Network/Services/ProfileService.swift b/Sources/Gravatar/Network/Services/ProfileService.swift index 91ed4040..10038ce5 100644 --- a/Sources/Gravatar/Network/Services/ProfileService.swift +++ b/Sources/Gravatar/Network/Services/ProfileService.swift @@ -1,12 +1,21 @@ import Foundation +/// A service to perform Profile related tasks. public struct ProfileService { private let client: HTTPClient + /// Creates a new `ProfileService`. + /// + /// Optionally, you can pass a custom type conforming to ``HTTPClient`` to gain control over networking tasks. + /// - Parameter client: A type which will perform basic networking operations. public init(client: HTTPClient? = nil) { self.client = client ?? URLSessionHTTPClient() } + /// Fetches a Gravatar user's profile information. + /// - Parameters: + /// - email: The user account email. + /// - onCompletion: The completion handler to call when the fetch request is complete. public func fetchProfile(with email: String, onCompletion: @escaping ((_ result: GravatarProfileFetchResult) -> Void)) { Task { do { @@ -20,6 +29,9 @@ public struct ProfileService { } } + /// Fetches a Gravatar user's profile information, and delivers the user profile asynchronously. + /// - Parameter email: The user account email. + /// - Returns: An asynchronously-delivered user profile. public func fetchProfile(for email: String) async throws -> GravatarProfile { let path = email.sha256() + ".json" do { diff --git a/Sources/Gravatar/Options/GravatarOptions.swift b/Sources/Gravatar/Options/GravatarOptions.swift index 046cb9e9..afa429d7 100644 --- a/Sources/Gravatar/Options/GravatarOptions.swift +++ b/Sources/Gravatar/Options/GravatarOptions.swift @@ -78,14 +78,17 @@ public struct ImageDownloadOptions { private let preferredSize: ImageSize? - /// ImageDownloadOptions initializer + /// Creates a new `GravatarImageDownloadOptions` with the given options. + /// + /// When passing `nil` to the optional parameters, the backend defaults are going to be used. + /// For more info about backend defaults, see https://docs.gravatar.com/general/images/ /// - Parameters: - /// - preferredSize: preferred image size (set to `nil` for default size) - /// - gravatarRating: maximum rating for image (set to `nil` for default rating) - /// - forceRefresh: force the image to be downloaded, ignoring the cache - /// - forceDefaultImage: force the default image to be used (set to `nil` for default value) - /// - defaultImageOption: configure the default image (set to `nil` to use the default default image) - /// - processor: processor for handling the downloaded `Data` + /// - preferredSize: Preferred image size (set to `nil` for default size) + /// - gravatarRating: Maximum rating for image (set to `nil` for default rating) + /// - forceRefresh: Force the image to be downloaded, ignoring the cache + /// - forceDefaultImage: If `true`, the returned image will always be the default image, determined by the `defaultImageOption` parameter. + /// - defaultImageOption: Configure the default image (set to `nil` to use the default default image) + /// - processingMethod: Method to use for processing the downloaded `Data` public init( preferredSize: ImageSize? = nil, rating: ImageRating? = nil, diff --git a/Sources/Gravatar/Options/ImageQueryOptions.swift b/Sources/Gravatar/Options/ImageQueryOptions.swift index 4dd05554..0c3d275a 100644 --- a/Sources/Gravatar/Options/ImageQueryOptions.swift +++ b/Sources/Gravatar/Options/ImageQueryOptions.swift @@ -19,7 +19,7 @@ public struct ImageQueryOptions { /// - gravatarRating: The lowest rating allowed to be displayed. If the requested email hash does not have an image meeting the requested rating level, /// - defaultImageOption: Choose what will happen if no Gravatar image is found. See ``DefaultImageOption`` for more info. /// then the default image is returned. - /// - forceDefaultImage: If set to `true`, the requested image will always be the default. + /// - forceDefaultImage: If set to `true`, the returned image will always be the default image, determined by the `defaultImageOption` parameter. public init( preferredSize: ImageSize? = nil, rating: ImageRating? = nil,