Merge pull request #33 from torusresearch/readme_fixes

feat: fix readme

Sources/ThresholdKey/Common/KeyPoint.swift

@@ -1,16 +1,17 @@
-//
-//  Point.swift
-//  tkey_ios
-//
-//  Created by David Main on 2022/11/01.
-//
-
 import Foundation
 #if canImport(lib)
     import lib
 #endif
 
 public final class KeyPoint: Equatable {
+
+    /// Compares two KeyPoint objects
+    ///
+    /// - Parameters:
+    ///   - lhs: First `KeyPoint` to compare.
+    ///   - rhs: Second `Keypoint` to compare.
+    ///
+    /// - Returns: `true` if they are equal, `false` otherwise
     public static func == (lhs: KeyPoint, rhs: KeyPoint) -> Bool {
         do {
             let lhsx = try lhs.getX()
@@ -30,10 +31,25 @@ public final class KeyPoint: Equatable {
 
     public var pointer: OpaquePointer?
 
+    /// Instantiate a `KeyPoint` object using the underlying pointer.
+    ///
+    /// - Returns: `KeyPoint`
+    ///
+    /// - Parameters:
+    ///   - pointer: The pointer to the underlying foreign function interface object.
     public init(pointer: OpaquePointer) {
         self.pointer = pointer
     }
 
+    /// Instantiates a `KeyPoint` object using X and Y co-ordinates in hexadecimal format.
+    ///
+    /// - Parameters:
+    ///   - x: X value of co-ordinate pair.
+    ///   - y: Y value of co-ordinate pair.
+    ///
+    /// - Returns: `KeyPoint` object.
+    ///
+    /// - Throws: `RuntimeError`, indicates invalid parameters was used.
     public init(x: String, y: String) throws {
         var errorCode: Int32 = -1
         let xPtr = UnsafeMutablePointer<Int8>(mutating: (x as NSString).utf8String)
@@ -47,6 +63,11 @@ public final class KeyPoint: Equatable {
         pointer = result;
     }
 
+    /// Retrieves the X value of the co-ordinate pair.
+    ///
+    /// - Returns: X value in hexadecimal format as `String`
+    ///
+    /// - Throws: `RuntimeError`, indicates underlying pointer is invalid.
     public func getX() throws -> String {
         var errorCode: Int32 = -1
         let result = withUnsafeMutablePointer(to: &errorCode, { error in
@@ -60,6 +81,11 @@ public final class KeyPoint: Equatable {
         return x
     }
 
+    /// Retrieves the Y value of the co-ordinate pair.
+    ///
+    /// - Returns: Y value in hexadecimal format as `String`
+    ///
+    /// - Throws: `RuntimeError`, indicates underlying pointer is invalid.
     public func getY() throws -> String {
         var errorCode: Int32 = -1
         let result = withUnsafeMutablePointer(to: &errorCode, { error in
@@ -73,15 +99,23 @@ public final class KeyPoint: Equatable {
         return y
     }
 
+    /// Gets the serialized form of a `KeyPoint`, should it be a valid PublicKey.
+    ///
+    /// - Parameters:
+    ///   - format: `"elliptic-compressed"` for the compressed form, otherwise the uncompressed form will be returned.
+    ///
+    /// - Returns: Serialized form of `KeyPoint` as `String`
+    ///
+    /// - Throws: `RuntimeError`, indicates either the underlying pointer is invalid or the co-ordinate pair is not a valid PublicKey.
     public func getAsCompressedPublicKey(format: String) throws -> String {
         var errorCode: Int32 = -1
 
-        let encoder_format = UnsafeMutablePointer<Int8>(mutating: ("elliptic-compressed" as NSString).utf8String)
+        let encoder_format = UnsafeMutablePointer<Int8>(mutating: (format as NSString).utf8String)
         let result = withUnsafeMutablePointer(to: &errorCode, { error in
             key_point_encode(pointer, encoder_format, error)
         })
         guard errorCode == 0 else {
-            throw RuntimeError("Error in KeyPoint, field Y")
+            throw RuntimeError("Error in KeyPoint, getAsCompressedPublicKey")
             }
         let compressed = String.init(cString: result!)
         string_free(result)

Sources/ThresholdKey/Common/PrivateKey.swift

@@ -1,10 +1,3 @@
-//
-//  PrivateKey.swift
-//  tkey_ios (iOS)
-//
-//  Created by David Main on 2022/11/01.
-//
-
 import Foundation
 #if canImport(lib)
     import lib
@@ -14,15 +7,32 @@ public final class PrivateKey {
     public var hex: String
     internal static let curveN = "fffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364141"
 
+    /// Instantiate a `PrivateKey` object using the underlying pointer.
+    /// 
+    /// - Parameters:
+    ///   - pointer: The pointer to the underlying foreign function interface object.
+    ///
+    /// - Returns: `PrivateKey` object.
     public init(pointer: UnsafeMutablePointer<Int8>) {
         hex = String.init(cString: pointer)
         string_free(pointer)
     }
 
+    /// Instantiates a `PrivateKey` object from its' serialized format.
+    ///
+    /// - Parameters:
+    ///   - hex: hexadecimal representation as `String`
+    ///
+    /// - Returns: `PrivateKey` object.
     public init(hex: String) {
         self.hex = hex
     }
 
+    /// Instantiates a `PrivateKey` object by random generation.
+    ///
+    /// - Returns: `PrivateKey` object.
+    ///
+    /// - Throws: `RuntimeError`, only possible if curveN is passed externally.
     public static func generate() throws -> PrivateKey {
         var errorCode: Int32 = -1
         let curvePointer = UnsafeMutablePointer<Int8>(mutating: (curveN as NSString).utf8String)

Sources/ThresholdKey/Common/ShareStore.swift

@@ -1,80 +1,107 @@
-//
-//  ShareStore.swift
-//  tkey_ios
-//
-//  Created by David Main.
-//
-
 import Foundation
 #if canImport(lib)
     import lib
 #endif
 
 public final class ShareStore {
     private(set) var pointer: OpaquePointer?
-
+
+    /// Instantiate a `ShareStore` object using the underlying pointer.
+    ///
+    /// - Parameters:
+    ///   - pointer: The pointer to the underlying foreign function interface object.
+    ///
+    /// - Returns: `ShareStore`
     public init(pointer: OpaquePointer) {
         self.pointer = pointer
     }
 
+    /// Instantiate a `ShareStore` object using its' corresponding json.
+    ///
+    /// - Parameters:
+    ///   - json: Json representation as a `String`.
+    ///
+    /// - Returns: `ShareStore`
+    ///
+    /// - Throws: `RuntimeError`, json is invalid.
     public init(json: String) throws {
         var errorCode: Int32 = -1
         let jsonPointer = UnsafeMutablePointer<Int8>(mutating: (json as NSString).utf8String)
         let result = withUnsafeMutablePointer(to: &errorCode, { error in
             share_store_from_json(jsonPointer, error)
                 })
         guard errorCode == 0 else {
-            throw RuntimeError("Error in ShareStore \(errorCode)")
+            throw RuntimeError("Error in ShareStore, json")
             }
         pointer = result
     }
 
+    /// Serialize a `ShareStore` object to its' corresponding json.
+    ///
+    /// - Returns: `String`
+    ///
+    /// - Throws: `RuntimeError`, underlying pointer is invalid
     public func toJsonString() throws -> String {
         var errorCode: Int32 = -1
         let result = withUnsafeMutablePointer(to: &errorCode, { error in
             share_store_to_json(pointer, error)
         })
         guard errorCode == 0 else {
-            throw RuntimeError("Error in ShareStore to Json \(errorCode)")
+            throw RuntimeError("Error in ShareStore toJsonString")
         }
         let string = String(cString: result!)
         string_free(result)
         return string
     }
 
+    /// Returns the Share contained in the `ShareStore` object.
+    ///
+    /// - Returns: `String`
+    ///
+    /// - Throws: `RuntimeError`, underlying pointer is invalid
     public func share() throws -> String {
         var errorCode: Int32 = -1
         let result = withUnsafeMutablePointer(to: &errorCode, { error in
             share_store_get_share(pointer, error)
                 })
         guard errorCode == 0 else {
-            throw RuntimeError("Error in ShareStore")
+            throw RuntimeError("Error in ShareStore, share")
             }
         let value = String.init(cString: result!)
         string_free(result)
         return value
     }
 
+    /// Returns the share index of the Share contained in the `ShareStore` object.
+    ///
+    /// - Returns: `String`
+    ///
+    /// - Throws: `RuntimeError`, underlying pointer is invalid
     public func share_index() throws -> String {
         var errorCode: Int32 = -1
         let result = withUnsafeMutablePointer(to: &errorCode, { error in
             share_store_get_share_index(pointer, error)
                 })
         guard errorCode == 0 else {
-            throw RuntimeError("Error in ShareStore")
+            throw RuntimeError("Error in ShareStore, share index")
             }
         let value = String.init(cString: result!)
         string_free(result)
         return value
     }
 
+    /// Returns the polynomial ID of the `ShareStore` object.
+    ///
+    /// - Returns: `String`
+    ///
+    /// - Throws: `RuntimeError`, underlying pointer is invalid
     public func polynomial_id() throws -> String {
         var errorCode: Int32 = -1
         let result = withUnsafeMutablePointer(to: &errorCode, { error in
             share_store_get_polynomial_id(pointer, error)
                 })
         guard errorCode == 0 else {
-            throw RuntimeError("Error in ShareStore")
+            throw RuntimeError("Error in ShareStore, polynomial id")
             }
         let value = String.init(cString: result!)
         string_free(result)

Sources/ThresholdKey/GenerateShareStoreResult.swift

@@ -1,10 +1,3 @@
-//
-//  GenerateShareStoreResult.swift
-//  tkey_ios
-//
-//  Created by David Main.
-//
-
 import Foundation
 #if canImport(lib)
     import lib
@@ -15,6 +8,14 @@ public final class GenerateShareStoreResult {
     public var hex: String
     public var share_store: ShareStoreMap
 
+    /// Instantiate a `GenerateShareStoreResult` object using the underlying pointer.
+    ///
+    /// - Parameters:
+    ///   - pointer: The pointer to the underlying foreign function interface object.
+    ///
+    /// - Returns: `GenerateShareStoreResult`
+    ///
+    ///   - Throws: `RuntimeError`, indicates underlying pointer is invalid.
     public init(pointer: OpaquePointer) throws {
         self.pointer = pointer
         var errorCode: Int32 = -1

Sources/ThresholdKey/KeyDetails.swift

@@ -1,10 +1,3 @@
-//
-//  KeyResult.swift
-//  tkey_ios
-//
-//  Created by David Main.
-//
-
 import Foundation
 #if canImport(lib)
     import lib
@@ -17,6 +10,14 @@ public final class KeyDetails {
     public let total_shares: UInt32
     public let share_descriptions: String
 
+    /// Instantiate a `KeyDetails` object using the underlying pointer.
+    ///
+    /// - Parameters:
+    ///   - pointer: The pointer to the underlying foreign function interface object.
+    ///
+    /// - Returns: `KeyDetails`
+    ///
+    /// - Throws: `RuntimeError`, indicates underlying pointer is invalid.
     public init(pointer: OpaquePointer) throws {
         var errorCode: Int32 = -1
         let point = withUnsafeMutablePointer(to: &errorCode, { error in