Improving docs of main types (#97)

* Improving docs of main types

Sources/Gravatar/Gravatar.docc/Gravatar.md

@@ -27,7 +27,7 @@ gravatarImageView.gravatar.setImage(email: "[email protected]")
 ```
 
 For more info check:
-- ``GravatarWrapper/setImage(email:placeholder:rating:preferredSize:options:completionHandler:)``
+- ``GravatarWrapper/setImage(email:placeholder:rating:preferredSize:defaultImage:options:completionHandler:)``
 
 ## Featured
 

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()
 }
 

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<T: Decodable>(from path: String) async throws -> T
 }

Sources/Gravatar/Network/Services/ImageDownloader.swift

@@ -3,25 +3,50 @@ import UIKit
 
 public typealias ImageDownloadCompletion = (Result<ImageDownloadResult, ImageFetchingError>) -> 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,
         processingMethod: ImageProcessingMethod,
         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,

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()

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,

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 {

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,

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,