From df723fef5a9a2683a0e85d1db4ab8fc76d88aee7 Mon Sep 17 00:00:00 2001
From: Kare Morstol <kare@nottoobadsoftware.com>
Date: Fri, 29 Aug 2014 01:44:49 +0200
Subject: [PATCH] Even more documentation.

---
 SwiftShell/Command.swift |  2 +-
 SwiftShell/Stream.swift  | 42 +++++++++++++++++++++++++++++-----------
 2 files changed, 32 insertions(+), 12 deletions(-)

diff --git a/SwiftShell/Command.swift b/SwiftShell/Command.swift
index bf44288..403729e 100644
--- a/SwiftShell/Command.swift
+++ b/SwiftShell/Command.swift
@@ -17,7 +17,7 @@ private func newtask (shellcommand: String) -> NSTask {
 }
 
 /** 
-Run a shellcommand synchronously with no standard input. 
+Run a shell command synchronously with no standard input. 
 
 :returns: Standard output
 */
diff --git a/SwiftShell/Stream.swift b/SwiftShell/Stream.swift
index 85f1972..1e4e90d 100644
--- a/SwiftShell/Stream.swift
+++ b/SwiftShell/Stream.swift
@@ -50,15 +50,29 @@ public func stream (text: String) -> ReadableStreamType {
 	return pipe.fileHandleForReading
 }
 
-public func stream ( closureclosure:() -> () -> String? ) -> ReadableStreamType {
-	let closure = closureclosure()
+/** 
+Creates a stream from a function returning a  generator function, which is called everytime the stream is  asked for more text.
+
+stream {
+	// initialisation...
+	return {
+		// called repeatedly by the resulting stream
+		// return text,	or return nil when done.
+	}
+}
+
+:returns:  The output stream.
+*/
+public func stream ( closure:() -> () -> String? ) -> ReadableStreamType {
+	let getmoretext = closure()
 	let pipe = NSPipe()
 	
 	let input: NSFileHandle = pipe.fileHandleForWriting
 	input.writeabilityHandler = { filehandle in 
-		if let text = closure() {
+		if let text = getmoretext() {
 			filehandle.write(text) 
 		} else {
+			// close the stream
 			input.writeabilityHandler = nil
 		}
 	}
@@ -66,6 +80,7 @@ public func stream ( closureclosure:() -> () -> String? ) -> ReadableStreamType
 	return pipe.fileHandleForReading
 }
 
+/** Creates a stream from a sequence of Strings. */
 public func stream <Seq:SequenceType where Seq.Generator.Element == String>(sequence: Seq) -> ReadableStreamType {
 	return stream {
 		var generator = sequence.generate()
@@ -73,7 +88,7 @@ public func stream <Seq:SequenceType where Seq.Generator.Element == String>(sequ
 	}
 }
 
-
+/** For splitting a stream into parts separated by "delimiter". */
 struct StringStreamGenerator : GeneratorType {
 	private let stream: ReadableStreamType
 	private	let delimiter: String
@@ -84,25 +99,30 @@ struct StringStreamGenerator : GeneratorType {
 		self.delimiter = delimiter
 	}
 	
+	/** Passes on the stream until the next occurrence of "delimiter" */
 	mutating func next () -> String? {
-		let (nextline, returnedseparator, remainder) = cache.partition(delimiter)
-		let separatorwasfound = returnedseparator != ""
+		let (nextpart, returneddelimiter, remainder) = cache.partition(delimiter)
+		let delimiterwasfound = returneddelimiter != ""
 		cache = remainder
 		
-		if separatorwasfound {
-			return nextline
+		if delimiterwasfound {
+			return nextpart
 		} else {
 			if let newcache = stream.readSome() {
-				cache = nextline + newcache 
+				// add the next part of the stream to what's left of the previous one, 
+				// and start again from the beginning of the function.
+				cache = nextpart + newcache 
 				return next()
 			} else {
-				return nextline == "" ? nil : nextline
+				// the stream is empty and there are no more delimiters left.
+				// return whatever is left, or nil if empty.
+				return nextpart == "" ? nil : nextpart
 			}
 		}
 	}
-	
 }
 
+/** Split a stream lazily */
 public func split(delimiter: String = "\n")(stream: ReadableStreamType) -> SequenceOf<String> {
 	return SequenceOf({StringStreamGenerator (stream: stream, delimiter: delimiter)})
 }