v10.0.1 (#143)

* Updated CHANGELOG.md
* Updated README.md
* Added code documentation

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Change Log
 
+## Version 10.0.1 (March 29, 2022)
+Minor update. 
+* Added inline code documentation.
+* Updated README.md.
+* Made `ResponseError` public.
+
 ## Version 10.0.0 (March 28, 2022)
 Major 'breaking' release. Highlights:
 * Replaces Swift Combine publishers with Swift Concurrency (async/await) model

Sources/SwiftlySalesforce/Connection+API.swift

@@ -5,13 +5,25 @@ public extension Connection {
     /// Retrieves information about limits in your org. 
     /// For each limit, this method returns the maximum allocation and the remaining allocation based on usage.
     /// 
-    /// See: [Limits](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_limits.htm)
+    /// [Limits](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_limits.htm)
+    ///
+    /// - Returns: A dictionary of ``Limit`` instances.
     ///
-    /// - Returns: A dictionary of ``Limit`` instances
     func limits() async throws -> [String: Limit] {
         return try await request(service: Resource.Limits())
     }
 
+    /// Performs a query.
+    ///
+    /// - [Query](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_query.htm)
+    /// - [SOQL and SOSL Reference](https://developer.salesforce.com/docs/atlas.en-us.232.0.soql_sosl.meta/soql_sosl/sforce_api_calls_soql_sosl_intro.htm)
+    ///
+    /// - Parameters:
+    ///     - soql: A SOQL query string.
+    ///     - batchSize: A numeric value that specifies the number of records returned for a query request.
+    /// 
+    /// - Returns: ``QueryResult``
+    ///
     func query<T: Decodable>(soql: String, batchSize: Int? = nil) async throws -> QueryResult<T> {
         return try await request(service: Resource.Query.Run(soql: soql, batchSize: batchSize))
     }
@@ -28,14 +40,45 @@ public extension Connection {
         return try await request(service: Resource.Query.MyRecords(type: type, fields: fields, limit: limit, batchSize: batchSize))
     }
 
+    /// Searches for a string in Salesforce record fields
+    ///
+    /// [SOQL and SOSL Reference](https://developer.salesforce.com/docs/atlas.en-us.232.0.soql_sosl.meta/soql_sosl/sforce_api_calls_soql_sosl_intro.htm)
+    ///
+    /// - Parameters:
+    ///     - sosl: A SOSL query string.
+    ///
+    /// - Returns:
+    ///     - An array of records that match the search criteria.
+    ///
     func search(sosl: String) async throws -> [Record] {
         return try await request(service: Resource.Search(sosl: sosl))
     }
 
+    /// Inserts a Salesforce record
+    ///
+    /// - Parameters:
+    ///     - type: Type of record (e.g. `Account`, `Contact` or `MyCustomObject__c`).
+    ///     - fields: Dictionary of fields names and values to insert.
+    ///
+    /// - Returns: Publisher that emits the ID of the successfully-inserted record, or an error.
+    ///
     func insert<T: Encodable>(type: String, fields: [String: T]) async throws -> String {
         return try await request(service: Resource.SObjects.Create(type: type, fields: fields))
     }
 
+    /// Retrieves a Salesforce record.
+    ///
+    /// [Working with Records](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/using_resources_working_with_records.htm)
+    ///
+    /// - Parameters:
+    ///     - type: Type of record (e.g. "Account", "Contact" or "MyCustomObject__c").
+    ///     - id: Unique ID of the record; 15 or 18 characters.
+    ///     - fields: Fields to retrieve. If nil, then all fields will be retrieved.
+    ///
+    /// - Returns: A Salesforce record.
+    ///
+    /// - Throws: ``ResponseError`` if the record can't be found or if the request can't be completed.
+    ///
     func read<T: Decodable>(type: String, id: String, fields: [String]? = nil) async throws -> T {
         return try await request(service: Resource.SObjects.Read(type: type, id: id, fields: fields))
     }
@@ -44,40 +87,76 @@ public extension Connection {
         return try await request(service: Resource.SObjects.Read(type: type, id: id, fields: fields))
     }
 
+    /// Updates a Salesforce record
+    ///
+    /// - Parameters:
+    ///     - type: Type of record (e.g. `Account`, `Contact` or `MyCustomObject__c`).
+    ///     - id: Unique ID of the record; 15 or 18 characters.
+    ///     - fields: Dictionary of fields names and values to update.
+    ///
+    /// - Returns: Void; no return value.
+    ///
     func update<T: Encodable>(type: String, id: String, fields: [String: T]) async throws -> Void {
         return try await request(service: Resource.SObjects.Update(type: type, id: id, fields: fields))
     }
 
+    /// Deletes a Salesforce record
+    ///
+    /// - Parameters:
+    ///     - type: Type of record (e.g. `Account`, `Contact` or `MyCustomObject__c`).
+    ///     - id: Unique ID of the record; 15 or 18 characters.
+    ///
+    /// - Returns: Void; no return value.
+    ///
     func delete(type: String, id: String) async throws -> Void {
         return try await request(service: Resource.SObjects.Delete(type: type, id: id))
     }
 
+    /// Retrieves metadata about a Salesforce object.
+    ///
+    /// [sObject Describe](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_sobject_describe.htm)
+    ///
+    /// - Parameters:
+    ///     - type: Type of record (e.g. `Account`, `Contact` or `MyCustomObject__c`).
+    ///
+    /// - Returns: An ``ObjectDescription`` instance.
+    ///
     func describe(type: String) async throws -> ObjectDescription {
         return try await request(service: Resource.SObjects.Describe(type: type))
     }
 
+    /// Describes all accessible objects in the user's Salesforce org.
+    ///
+    /// [sObject Describe](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_sobject_describe.htm)
+    ///
+    /// - Returns: An array of ``ObjectDescription`` instances.
+    ///
     func describeGlobal() async throws -> [ObjectDescription] {
         return try await request(service: Resource.SObjects.DescribeGlobal())
     }
 
     /// Gets information about the current user
+    ///
     /// - Returns: An ``Identity`` instance.
+    ///
     func identity() async throws -> Identity {
         return try await request(service: IdentityService())
     }
 
-    /// Represents a call to an Apex class exposed as a REST service.
+    /// Calls an Apex class exposed as a REST service.
     ///
-    /// See [Introduction to Apex REST](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_rest_intro.htm) in the Salesforce documentation.
+    /// [Introduction to Apex REST](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_rest_intro.htm)
     ///
     /// - Parameters:
-    ///   - method: Optional, HTTP method to use; if `nil` then GET will be used in the request.
-    ///   - path: Path to the Apex REST service, as defined in the `urlMapping` of the `@RestResource` annotation on the target class.
-    ///   - queryItems: Optional query items to include in the request.
-    ///   - headers: Optional `HTTP` headers to include in the request.
-    ///   - body: Request body for a `POST` , `PATCH` or `PUT`  request.
-    ///   - timeoutInterval: request timeout interval, in seconds.
+    ///     - method: Optional, HTTP method to use; if `nil` then GET will be used in the request.
+    ///     - path: Path to the Apex REST service, as defined in the `urlMapping` of the `@RestResource` annotation on the target class.
+    ///     - queryItems: Optional query items to include in the request.
+    ///     - headers: Optional `HTTP` headers to include in the request.
+    ///     - body: Request body for a `POST` , `PATCH` or `PUT`  request.
+    ///     - timeoutInterval: request timeout interval, in seconds.
+    ///
     /// - Returns: The `Decodable` return value from the Apex class.
+    ///
     func apex<T: Decodable>(
         method: String? = nil,
         path: String,

Sources/SwiftlySalesforce/Errors/ResponseError.swift

@@ -1,11 +1,11 @@
 import Foundation
 
-struct ResponseError: Error {
+public struct ResponseError: Error {
 
-    var code: String? = nil
-    var message: String? = nil
-    var fields: [String]? = nil
-    let metadata: HTTPURLResponse
+    public var code: String? = nil
+    public var message: String? = nil
+    public var fields: [String]? = nil
+    public let metadata: HTTPURLResponse
 
     private let na = "N/A" // 'Not Applicable' or 'Not Available'
 }
@@ -19,7 +19,7 @@ extension ResponseError: LocalizedError {
 
 extension ResponseError: CustomDebugStringConvertible {
 
-    var debugDescription: String {
+    public var debugDescription: String {
         let na = "N/A" // 'Not Applicable' or 'Not Available'
         let fieldStr = fields?.joined(separator: ", ") ?? na
         return "Salesforce response error. Code: \(code ?? na). Message: \(message ?? na). Fields: \(fieldStr). HTTP Status Code: \(metadata.statusCode))"