Create Screen concept and add some documentation

ChaiOS/Classes/Action.swift

@@ -1,6 +1,11 @@
 import Foundation
 import EarlGrey
 
+/**
+ Enum for performing actions on views.
+
+ Provides a lot of action methods, such as .tap, .scrollInDirection, etc.
+*/
 public enum Action {
     case scrollInDirection(Direction, amount: CGFloat)
     case scrollToContentEdge(ContentEdge)

ChaiOS/Classes/ChaiOS.swift

@@ -1,53 +1,49 @@
 import Foundation
 import EarlGrey
 
-// TODO: Document the class
+/**
+ Static container generic UI interaction methods,
+ such as rotate the device screen or close the keyboard.
+*/
 public final class ChaiOS {
-
-    public static func with(_ matcher: Matcher) -> Interaction {
-        return Interaction(matcher: matcher)
-    }
-
-    public static func that(_ condition: Condition) -> Matcher {
-        return Matcher.that(condition)
-    }
-
-    public static func any(_ conditions: Condition...) -> Matcher {
-        return Matcher.any(conditions)
-    }
-
-    public static func all(_ conditions: Condition...) -> Matcher {
-        return Matcher.all(conditions)
-    }
-
-    public static func any(_ conditions: [Condition]) -> Matcher {
-        return Matcher.any(conditions)
-    }
-
-    public static func all(_ conditions: [Condition]) -> Matcher {
-        return Matcher.all(conditions)
-    }
-}
-
-extension ChaiOS {
-
-    public static func rotateDevice(to orientation: UIDeviceOrientation) throws {
-        var error: NSError?
-        EarlGreyImpl.invoked(fromFile: #file, lineNumber: #line).rotateDevice(to: orientation, errorOrNil: &error)
-        if let error = error {
-            throw error
-        }
-    }
-
-    public static func dismissKeyboard() throws {
-        var error: NSError?
-        EarlGreyImpl.invoked(fromFile: #file, lineNumber: #line).dismissKeyboardWithError(&error)
-        if let error = error {
-            throw error
-        }
-    }
-
-    public static func condition(with: Matcher) -> Interaction {
-
-    }
+
+	public static func rotateDevice(to orientation: UIDeviceOrientation) throws {
+		var error: NSError?
+		EarlGreyImpl.invoked(fromFile: #file, lineNumber: #line).rotateDevice(to: orientation, errorOrNil: &error)
+		if let error = error {
+			throw error
+		}
+	}
+
+	public static func dismissKeyboard() throws {
+		var error: NSError?
+		EarlGreyImpl.invoked(fromFile: #file, lineNumber: #line).dismissKeyboardWithError(&error)
+		if let error = error {
+			throw error
+		}
+	}
+
+	public static func with(_ matcher: Matcher) -> Interaction {
+		return Interaction(matcher: matcher)
+	}
+
+	public static func that(_ condition: Condition) -> Matcher {
+		return Matcher.that(condition)
+	}
+
+	public static func any(_ conditions: Condition...) -> Matcher {
+		return Matcher.any(conditions)
+	}
+
+	public static func all(_ conditions: Condition...) -> Matcher {
+		return Matcher.all(conditions)
+	}
+
+	public static func any(_ conditions: [Condition]) -> Matcher {
+		return Matcher.any(conditions)
+	}
+
+	public static func all(_ conditions: [Condition]) -> Matcher {
+		return Matcher.all(conditions)
+	}
 }

ChaiOS/Classes/Interaction.swift

@@ -1,6 +1,11 @@
 import Foundation
 import EarlGrey
 
+/**
+ Provides the primary methods for test authors to perform actions or asserts on views.
+
+ Each interaction is associated with a view identified by a matcher.
+*/
 public class Interaction: GreyConvertible {
 
     public typealias Grey = GREYInteraction
@@ -24,7 +29,10 @@ public class Interaction: GreyConvertible {
     public var toGrey: GREYInteraction {
         return index == nil ? selection : selection.atIndex(index!)
     }
-
+
+	/**
+	 Asserts the given condition on the view selected by the current matcher.
+	*/
     @discardableResult
     public func assert(_ condition: Condition) -> Self {
         var selection = self.selection
@@ -34,7 +42,7 @@ public class Interaction: GreyConvertible {
         selection.assert(condition.toGrey)
         return self
     }
-    
+	
     @discardableResult
     public func assert(_ otherMatcher: Matcher) -> Self {
         self.toGrey.assert(otherMatcher.toGrey)
@@ -52,7 +60,9 @@ public class Interaction: GreyConvertible {
         self.toGrey.using(searchAction: action.toGrey, onElementWithMatcher: matcher.toGrey)
         return self
     }
-
+	/**
+	 Performs the given action on the view selected by the current matcher.
+	*/
     @discardableResult
     public func perform(_ action: Action) -> Self {
         self.toGrey.__perform(action.toGrey)

ChaiOS/Classes/Matcher.swift

@@ -1,9 +1,15 @@
 import Foundation
 import EarlGrey
 
+/**
+ A matcher over acceptable conditions.
+*/
 public enum Matcher {
+	///Returns a Matcher associated to the view that satisfy the given condition.
     case that(Condition)
+	///Returns a Matcher associated to the view that satisfy any of the given conditions.
     case any([Condition])
+	///Returns a Matcher associated to the view that satisfy all the given conditions.
     case all([Condition])
 }
 
@@ -23,14 +29,18 @@ extension Matcher: GreyConvertible {
 }
 
 extension Matcher {
-
-    public func selected(file: StaticString = #file, line: UInt = #line) -> Interaction {
-        return Interaction.init(file: file, line: line, matcher: self)
-    }
-
-    public subscript(_ at: UInt) -> Interaction {
-        return Interaction(matcher: self, index: at)
-    }
+
+	public func selected(file: StaticString = #file, line: UInt = #line, closure: (Interaction) -> Void) {
+		closure(Interaction.init(file: file, line: line, matcher: self))
+	}
+
+	public func selected(file: StaticString = #file, line: UInt = #line) -> Interaction {
+		return Interaction.init(file: file, line: line, matcher: self)
+	}
+
+	public subscript(_ at: UInt) -> Interaction {
+		return Interaction(matcher: self, index: at)
+	}
 }
 
 extension Matcher {

ChaiOS/Classes/Screen.swift

@@ -0,0 +1,40 @@
+import Foundation
+
+/**
+Protocol for container classes of UI elements.
+
+This protocol groups UI elements and grants access to basic actions,
+such as perform() and assert()
+*/
+public protocol Screen { }
+
+extension Screen {
+
+	public func test(_ closure: (Self) -> Void) {
+		closure(self)
+	}
+
+	public static func with(_ matcher: Matcher) -> Interaction {
+		return ChaiOS.with(matcher)
+	}
+
+	public static func that(_ condition: Condition) -> Matcher {
+		return ChaiOS.that(condition)
+	}
+
+	public static func any(_ conditions: Condition...) -> Matcher {
+		return ChaiOS.any(conditions)
+	}
+
+	public static func all(_ conditions: Condition...) -> Matcher {
+		return ChaiOS.all(conditions)
+	}
+
+	public static func any(_ conditions: [Condition]) -> Matcher {
+		return ChaiOS.any(conditions)
+	}
+
+	public static func all(_ conditions: [Condition]) -> Matcher {
+		return ChaiOS.all(conditions)
+	}
+}