update function documentation

Author: zhangliugang

Sources/Web3Core/Contract/ContractProtocol.swift

@@ -143,7 +143,10 @@ public protocol ContractProtocol {
     ///     - name with arguments:`myFunction(uint256)`.
     ///     - method signature (with or without `0x` prefix, case insensitive): `0xFFffFFff`;
     ///   - data: non empty bytes to decode;
-    /// - Returns: dictionary with decoded values. `nil` if decoding failed.
+    /// - Returns: dictionary with decoded values.
+    /// - Throws:
+    ///   - `Web3Error.revert(String, String?)` when function call aborted by `revert(string)` and `require(expression, string)`.
+    ///   - `Web3Error.revertCustom(String, Dictionary)` when function call aborted by `revert CustomError()`.
     @discardableResult
     func decodeReturnData(_ method: String, data: Data) throws -> [String: Any]
 

Sources/Web3Core/EthereumABI/ABIElements.swift

@@ -202,7 +202,7 @@ extension ABI.Element.Constructor {
 extension ABI.Element.Function {
 
     /// Encode parameters of a given contract method
-    /// - Parameter parameters: Parameters to pass to Ethereum contract
+    /// - Parameters: Parameters to pass to Ethereum contract
     /// - Returns: Encoded data
     public func encodeParameters(_ parameters: [Any]) -> Data? {
         guard parameters.count == inputs.count,
@@ -223,6 +223,10 @@ extension ABI.Element.Event {
 // MARK: - Decode custom error
 
 extension ABI.Element.EthError {
+    /// Decodes `revert CustomError(_)` calls.
+    /// - Parameters:
+    ///  - data: bytes returned by a function call that stripped error signature hash.
+    /// - Returns: a dictionary containing decoded data mappend to indices and names of returned values or nil if decoding failed.
     public func decodeEthError(_ data: Data) -> [String: Any]? {
         guard inputs.count * 32 <= data.count,
               let decoded = ABIDecoder.decode(types: inputs, data: data) else {
@@ -239,7 +243,7 @@ extension ABI.Element.EthError {
         return result
     }
 
-    /// Decodes `revert(string)` and `require(expression, string)` calls.
+    /// Decodes `revert(string)` or `require(expression, string)` calls.
     /// These calls are decomposed as `Error(string)` error.
     public static func decodeStringError(_ data: Data) -> String? {
         let decoded = ABIDecoder.decode(types: [.init(name: "", type: .string)], data: data)
@@ -299,68 +303,36 @@ extension ABI.Element.Function {
         return ABIDecoder.decodeInputData(rawData, methodEncoding: methodEncoding, inputs: inputs)
     }
 
-    /// Decodes data returned by a function call. Able to decode `revert(string)`, `revert CustomError(...)` and `require(expression, string)` calls.
+    /// Decodes data returned by a function call.
     /// - Parameters:
     ///  - data: bytes returned by a function call;
-    ///  - errors: optional dictionary of known errors that could be returned by the function you called. Used to decode the error information.
     /// - Returns: a dictionary containing decoded data mappend to indices and names of returned values if these are not `nil`.
-    /// If `data` is an error response returns dictionary containing all available information about that specific error. Read more for details.
+    /// - Throws:
+    ///  - `Web3Error.processingError(desc: String)` when decode process failed.
     ///
     /// Return cases:
-    /// - when no `outputs` declared and `data` is not an error response:
+    /// - when no `outputs` declared:
     /// ```swift
-    /// ["_success": true]
+    /// [:]
     /// ```
     /// - when `outputs` declared and decoding completed successfully:
     /// ```swift
-    /// ["_success": true, "0": value_1, "1": value_2, ...]
+    /// ["0": value_1, "1": value_2, ...]
     /// ```
     /// Additionally this dictionary will have mappings to output names if these names are specified in the ABI;
-    /// - function call was aborted using `revert(message)` or `require(expression, message)`:
-    /// ```swift
-    /// ["_success": false, "_abortedByRevertOrRequire": true, "_errorMessage": message]`
-    /// ```
-    /// - function call was aborted using `revert CustomMessage()` and `errors` argument contains the ABI of that custom error type:
-    /// ```swift
-    /// ["_success": false,
-    /// "_abortedByRevertOrRequire": true,
-    /// "_error": error_name_and_types, // e.g. `MyCustomError(uint256, address senderAddress)`
-    /// "0": error_arg1,
-    /// "1": error_arg2,
-    /// ...,
-    /// "error_arg1_name": error_arg1, // Only named arguments will be mapped to their names, e.g. `"senderAddress": EthereumAddress`
-    /// "error_arg2_name": error_arg2, // Otherwise, you can query them by position index.
-    /// ...]
-    /// ```
-    /// - in case of any error:
-    /// ```swift
-    /// ["_success": false, "_failureReason": String]
-    /// ```
-    /// Error reasons include:
-    /// -  `outputs` declared but at least one value failed to be decoded;
-    /// - `data.count` is less than `outputs.count * 32`;
-    /// - `outputs` defined and `data` is empty;
-    /// - `data` represent reverted transaction
-    ///
-    /// How `revert(string)` and `require(expression, string)` return value is decomposed:
-    ///  - `08C379A0` function selector for `Error(string)`;
-    ///  - next 32 bytes are the data offset;
-    ///  - next 32 bytes are the error message length;
-    ///  - the next N bytes, where N >= 32, are the message bytes
-    ///  - the rest are 0 bytes padding.
     public func decodeReturnData(_ data: Data) throws -> [String: Any] {
         guard !outputs.isEmpty else {
             NSLog("Function doesn't have any output types to decode given data.")
             return [:]
         }
 
         guard outputs.count * 32 <= data.count else {
-            throw Web3Error.revert("Bytes count must be at least \(outputs.count * 32). Given \(data.count). Decoding will fail.", reason: nil)
+            throw Web3Error.processingError(desc: "Bytes count must be at least \(outputs.count * 32). Given \(data.count). Decoding will fail.")
         }
 
         // TODO: need improvement - we should be able to tell which value failed to be decoded
         guard let values = ABIDecoder.decode(types: outputs, data: data) else {
-            throw Web3Error.revert("Failed to decode at least one value.", reason: nil)
+            throw Web3Error.processingError(desc: "Failed to decode at least one value.")
         }
         var returnArray: [String: Any] = [:]
         for i in outputs.indices {
@@ -411,7 +383,7 @@ extension ABI.Element.Function {
     /// // "_parsingError" is optional and is present only if decoding of custom error arguments failed
     /// "_parsingError": "Data matches MyCustomError(uint256, address senderAddress) but failed to be decoded."]
     /// ```
-    @available(*, deprecated, message: "Use `ABI.Element.EthError.decodeEthError(_:)` instead")
+    @available(*, deprecated, message: "Use decode function from `ABI.Element.EthError` instead")
     public func decodeErrorResponse(_ data: Data, errors: [String: ABI.Element.EthError]? = nil) -> [String: Any]? {
         /// If data is empty and outputs are expected it is treated as a `require(expression)` or `revert()` call with no message.
         /// In solidity `require(false)` and `revert()` calls return empty error response.