Merge branch 'adam/improve-documentation' of github.com:TheAdamBorek/…

…Bento into adam/improve-documentation

Bento/Bento/Node.swift

@@ -2,7 +2,7 @@ import UIKit
 
 /// Node is kept by a Section. Node requires an identifier for diff algorithm.
 /// Node **always has** a visual representation, because a component needs to be provided.
-/// To simplify, you can think Node is in Bento the same what a cell is for UITableView.
+/// To simplify, you can think of a Node in Bento as equivalent to a cell in UITableView / UICollectionView.
 public struct Node<Identifier: Hashable> {
     public let id: Identifier
     let component: AnyRenderable

Bento/Bento/Section.swift

@@ -1,8 +1,8 @@
 import UIKit
 
-/// Section is kept usually by a Box while section keeps array of nodes. SectionID needs to be provided for diff algorithm
-/// Section **can have** a visual representation if components are provided (header and/or footer).
-/// To simplify, you can think Section is in Bento the same what a section is for UITableView.
+/// Section is part of a Box and holds an array of nodes. SectionID needs to be provided for the diffing algorithm.
+/// Section **can** have a visual representation if components are provided for the header and/or footer.
+/// To simplify, you can think of a Section in Bento as equivalent to a section in a UITableView.
 public struct Section<SectionID: Hashable, ItemID: Hashable> {
     public typealias Item = Node<ItemID>
 

Bento/Renderable/Renderable.swift

@@ -1,7 +1,7 @@
 import UIKit
 
-/// Protocol which every Component needs to conform.
-/// - View: UIView subtype which the component is releated with.
+/// Protocol which every Component needs to conform to.
+/// - View: UIView subtype which is the top level view type of the component.
 public protocol Renderable {
     associatedtype View: NativeView
 

Bento/Views/Box.swift

@@ -16,8 +16,8 @@ infix operator |---+: NodeConcatenationPrecedence
 infix operator |---*: NodeConcatenationPrecedence
 infix operator |---?: NodeConcatenationPrecedence
 
-/// Box keeps array of section which should be displayed on the screen.
-/// Box **doesn't have** a visual representation.
+/// Box holds an array of sections which should be displayed on the screen.
+/// Box **doesn't** have a visual representation.
 public struct Box<SectionID: Hashable, ItemID: Hashable> {
     public typealias Section = Bento.Section<SectionID, ItemID>
 

BentoKit/BentoKit/Components/Component.swift

@@ -1,2 +1,2 @@
-/// Typespace for all Components so they are easily located with Xcode hints.
+/// Namespace for all Components so they are easily located with Xcode hints.
 public enum Component {}

BentoKit/BentoKit/Components/DatePicker.swift

@@ -8,8 +8,8 @@ extension Component {
 
         /// Creates Component.DatePicker
         /// - parameter date: Date which should be preselected when opening the DatePicker.
-        /// - parameter minDate: Minimal range of possible dates.
-        /// - parameter maxDate: Maximum range of possible dates.
+        /// - parameter minDate: Minimum allowable date.
+        /// - parameter maxDate: Maximum allowable date.
         /// - parameter datePickerMode: Mode of a picker (date, date & time, etc.).
         /// - parameter styleSheet: StyleSheet with styling.
         /// - parameter didPickDate: Closure which is invoked when a date is selected.

BentoKit/BentoKit/Components/Search.swift

@@ -9,7 +9,7 @@ extension Component {
         /// Creates Component.Search which representes UISearchBar from iOS.
         /// - parameter placeholder: Text displayed when searchField is empty.
         /// - parameter keyboardType: Type of the keybaord used for editing.
-        /// - parameter didBeginEdition: Notifies when searchBar becomes firstResponder.
+        /// - parameter didBeginEditing: Notifies when searchBar becomes first responder.
         /// - parameter textDidChange: Notifies when text changes.
         /// - parameter showsCancelButton: Shows/hides the cancel button.
         /// - parameter cancelButtonClicked: Notifies that cancel button has been clicked.

BentoKit/BentoKit/Components/TextInput.swift

@@ -12,8 +12,8 @@ extension Component {
         /// Creates Component.TextInput
         /// - parameter title: Label of a the text input which describes it (i.e: "E-mail").
         /// - parameter placeholder: Placeholder which is displayed instead of text when text is empty.
-        /// - parameter text: Prefilled value of the TextInput. It can be modifed by user. (i.e: "[email protected]"). Limited to only one line.
-        /// - parameter keyboardType: iOS keyboard type.
+        /// - parameter text: Pre-filled value of the TextInput. It can be modifed by user. (i.e: "[email protected]"). Limited to only one line.
+        /// - parameter keyboardType: UIKit keyboard type.
         /// - parameter isEnabled: Indicates if user can change a text value.
         /// - parameter accessory: Additional icon displayed on the right side.
         /// - parameter textWillChange: Closure which may rejected text changes.

BentoKit/BentoKit/Components/TitledDescription.swift

@@ -36,7 +36,7 @@ public extension Component {
 
         /// Creates a TitledDescription
         /// - parameter texts: Array of TextValues which are displayed vertically on left side of the row.
-        /// - parameter detail: Description field displayed on the right side to `texts`
+        /// - parameter detail: Description field displayed to the right of `texts`
         /// - parameter image: Usually an image wrapped within `ImageOrLabel` component. Property makes it possible to be loaded async.
         ///                    However, you need to guarantee fixed size across all changes.
         /// - parameter accessory: Accessory which should be displayed near the right edge of the row.

BentoKit/BentoKit/Components/Toggle.swift

@@ -10,11 +10,11 @@ extension Component {
 
         /// Creates Component.Toggle
         /// - parameter title: Name/label/title of a row which is displayed on the left side.
-        /// - parameter attributedTitle: The same as `title` but allows for using text attributes.
+        /// - parameter attributedTitle: The same as `title` but allows for using attributed text.
         /// - parameter image: Icon displayed on the left side of the row.
         /// - parameter isOn: Indicates if the toggle shows true or false.
         /// - parameter isEnabled: Indicates if user can change value of the toggle.
-        /// - parameter isRefreshing: If `true` it displays UIActivityIndicator` instead of the switch view.
+        /// - parameter isRefreshing: If `true` it displays `UIActivityIndicator` instead of the switch view.
         /// - parameter animateValueChange: Indicates if should animate setting of the `isOn` value.
         /// - parameter styleSheet: StyleSheet with styling.
         /// - parameter didChangeValue: Closure which notifies about true/false change.

README.md

@@ -73,7 +73,7 @@ In other words, for Bento to work, it cannot be overridden with your own data so
 
 #### Box 📦
 
-`Box ` is a fundamental component of the library, essentially a virtual representation of the `UITableView` content. It has two generic parameters - `SectionId` and `RowId` - which are unique identifiers for  `Section<SectionId, RowId>` and `Node<RowId>`, used by the [diffing engine](https://github.com/RACCommunity/FlexibleDiff) to perform animated changes of the `UITableView` content. Box it's just a wrapper around array of sections.
+`Box ` is a fundamental component of the library, essentially a virtual representation of the `UITableView` content. It has two generic parameters - `SectionId` and `RowId` - which are unique identifiers for  `Section<SectionId, RowId>` and `Node<RowId>`, used by the [diffing engine](https://github.com/RACCommunity/FlexibleDiff) to perform animated changes of the `UITableView` content. Box is just a container for an array of sections.
 
 #### Sections and Nodes 🏗