Ks1019/add documentation

Sources/ScriptSwift/Script+Comparable.swift

@@ -1,8 +1,9 @@
 /// Scripting methods whose values are comparable
 extension Script where T: Comparable {
-    /// Return Bool value by comparing the piped value and the parameter `number`.
-    ///
+
     /// This method return true when the piped value is more than `number` and false otherwise.
+    /// - Parameter number: `Comparable` value
+    /// - Returns: Bool value by comparing the piped value and the parameter `number`
     public func more(than number: T) -> Script<Bool> {
         switch input {
         case .success(let input):
@@ -12,9 +13,9 @@ extension Script where T: Comparable {
         }
     }
 
-    /// Return Bool value by comparing the piped value and the parameter `number`.
-    ///
     /// This method return true when the piped value is less than `number` and false otherwise.
+    /// - Parameter number: `Comparable` value
+    /// - Returns: Bool value by comparing the piped value and the parameter `number`
     public func less(than number: T) -> Script<Bool> {
         switch input {
         case .success(let input):
@@ -24,9 +25,9 @@ extension Script where T: Comparable {
         }
     }
 
-    /// Return Bool value by comparing the piped value and the parameter `number`.
-    ///
     /// This method return true when the piped value is equal to `number` and false otherwise.
+    /// - Parameter number: `Comparable` value
+    /// - Returns: Bool value by comparing the piped value and the parameter `number`
     public func equal(to number: T) -> Script<Bool> {
         switch input {
         case .success(let input):

Sources/ScriptSwift/Script+Data.swift

@@ -2,6 +2,9 @@ import struct Foundation.Data
 import Files
 
 extension Script where T == Data {
+    /// This function writes `Data` value from previous ``Script`` method to a file specified.
+    /// - Parameter path: `String` representation of path of the file
+    /// - Returns: ``Script`` object with `File` value or failure
     public func write(path: String) -> Script<File> {
         switch input {
         case .success(let input):
@@ -18,6 +21,9 @@ extension Script where T == Data {
         }
     }
 
+    /// This function writes `Data` value from previous ``Script`` method to a file specified.
+    /// - Parameter filename: `String` representation of the name of the file
+    /// - Returns: ``Script`` object with `File` value or failure
     public func write(to filename: String) -> Script<File> {
         switch input {
         case .success(let input):

Sources/ScriptSwift/Script+Files.swift

@@ -2,6 +2,8 @@ import struct Foundation.Data
 import Files
 
 extension Script where T == File {
+    /// This function reads file from the value of the previous ``Script`` method.
+    /// - Returns: ``Script`` object with `Data` representation of the file or failure
     public func read() -> Script<Data> {
         switch input {
         case .success(let input):
@@ -16,6 +18,9 @@ extension Script where T == File {
         }
     }
 
+    /// This function reads file from the value of the previous ``Script`` method.
+    /// - Parameter encoded: This indicates how the file is encoded.
+    /// - Returns: ``Script`` object with `String` representation of the file or failure
     public func read(encoded: String.Encoding = .utf8) -> Script<String> {
         switch input {
         case .success(let input):

Sources/ScriptSwift/Script+String.swift

@@ -6,6 +6,8 @@ extension Script where T == String {
         self.init(success: "")
     }
 
+    /// This function executes externtal command using the input `String` value.
+    /// - Returns: ``Script`` object containing `String` value or failure
     public func exec() -> Script<String> {
         switch input {
         case .success(let input):
@@ -20,6 +22,8 @@ extension Script where T == String {
         }
     }
 
+    /// This function pass `self` to next function in the method chain if a file exists using the input `String` value.
+    /// - Returns: ``Script`` object passed from previous function or failure
     public func ifExists() -> Script<String> {
         switch input {
         case .success(let input):
@@ -34,6 +38,9 @@ extension Script where T == String {
         }
     }
 
+    /// This function passes `String` value only when matched.
+    /// - Parameter string: `String` value to match
+    /// - Returns: ``Script`` object with only matched `String` value or failure
     public func match(_ string: String) -> Script<String> {
         switch input {
         case .success(let input):
@@ -48,6 +55,8 @@ extension Script where T == String {
         }
     }
 
+    /// This function returns the number of lines of `String` input value.
+    /// - Returns: ``Script`` object with `Int` value of the number of lines
     public func countLines() -> Script<Int> {
         switch input {
         case .success(let input):
@@ -57,6 +66,8 @@ extension Script where T == String {
         }
     }
 
+    /// This function combines files using input `String` value as file names, and outputs the combined files as  `Array` of `String`.
+    /// - Returns:  ``Script`` object with `Array` of `String`
     public func concat() -> Script<[String]> {
         switch input {
         case .success(let input):
@@ -72,6 +83,8 @@ extension Script where T == String {
         }
     }
 
+    /// This function passes multi-line `String` value as `Array` to next ``Script`` method.
+    /// - Returns: ``Script`` object with `Array` of `String` value
     public func asArray() -> Script<[String]> {
         switch input {
         case .success(let input):

Sources/ScriptSwift/Script.swift

@@ -2,6 +2,9 @@ import Files
 import ShellOut
 import struct Foundation.Data
 
+/// Script type
+///
+/// By using method chain, you can express a workflow of your script in Swift.
 public struct Script<T> {
     var input: Result<T, Error>
 
@@ -17,16 +20,14 @@ public struct Script<T> {
         self.init(input: .failure(failure))
     }
 
+    /// This function collects inputs from stdin and returns as `String`.
+    /// - Returns: ``Script`` object containing `String` value or failure
     public func stdin() -> Script<String> {
         guard let array: [String] = readLine()?.split(separator: " ").map({ s in String(s) }) else { return .init(success: "") }
         return .init(success: array.joined(separator: " "))
     }
 
-    // public func stdin() -> Script<[String]> {
-    //     guard let array: [String] = readLine()?.split(separator: " ").map({ s in String(s) }) else { return .init(success: []) }
-    //     return .init(success: array)
-    // }
-
+    /// This function accepts inputs and outputs it to stdout.
     public func stdout() {
         switch input {
         case .success(let input):
@@ -36,6 +37,9 @@ public struct Script<T> {
         }
     }
 
+    /// This function executes externtal command.
+    /// - Parameter command: `Array` of `String` to execute command
+    /// - Returns: ``Script`` object containing `String` value or failure
     public func exec(_ command: [String]) -> Script<String> {
         do {
             return .init(success: try shellOut(to: command))
@@ -44,6 +48,9 @@ public struct Script<T> {
         }
     }
 
+    /// This function executes externtal command.
+    /// - Parameter command: `String` to execute command
+    /// - Returns: ``Script`` object containing `String` value or failure
     public func exec(_ command: String) -> Script<String> {
         do {
             return .init(success: try shellOut(to: command))
@@ -52,6 +59,9 @@ public struct Script<T> {
         }
     }
 
+    /// This function pass `self` to next function in the method chain if a file exists.
+    /// - Parameter filename: `String` to represent name of a file
+    /// - Returns: ``Script`` object passed from previous function or failure
     public func ifExists(_ filename: String) -> Script<T> {
         do {
             _ = try File(path: filename)
@@ -61,6 +71,9 @@ public struct Script<T> {
         }
     }
 
+    /// This function lets user modify the contained value in the method chain.
+    /// - Parameter transform: A closure to modify the contained value
+    /// - Returns: ``Script`` object with modified value or failure
     public func map<N>(_ transform: (T) -> N) -> Script<N> {
         switch input {
         case .success(let input):
@@ -70,6 +83,8 @@ public struct Script<T> {
         }
     }
 
+    /// This function returns the contained value, ending the method chain.
+    /// - Returns: The contained value or exit with failure
     public func raw() -> T {
         switch input {
         case .success(let input):
@@ -79,6 +94,8 @@ public struct Script<T> {
         }
     }
 
+    /// This function returns the contained value or error as `String`.
+    /// - Returns: `String` representaion of the contained value or error
     public func asString() -> String {
         switch input {
         case .success(let input):

Sources/ScriptSwift/SystemCall.swift

@@ -6,6 +6,9 @@ import Glibc
 let _exit = Glibc.exit
 #endif
 
+/// This function exit current process with error if given.
+/// - Parameter error: `Error` object
+/// - Returns: `Never`
 func exit(withError error: Error? = nil) -> Never {
     guard let error = error else {
         _exit(0)