Merge branch 'master' into feature/proper-tests

Author: Baris Sencan

README.md

@@ -26,7 +26,63 @@ Not yet available.
 
 #Usage
 
-Coming soon.
+Just `import ManualLayout` in your code and use the methods and properties provided by the library to layout your views.
+
+###A Simple Example
+
+Here is the complete code for a basic view controller.
+
+```swift
+import Foundation
+import ManualLayout
+
+internal final class ExampleViewController: UIViewController {
+  let titleLabel = UILabel(frame: CGRectZero)
+  let subtitleLabel = UILabel(frame: CGRectZero)
+  let yinView = UIView(frame: CGRectZero)
+  
+  override init() {
+    super.init(nibName: nil, bundle: nil)
+    titleLabel.attributedText = NSAttributedString(
+      string: "Hello World!",
+      attributes: generateTextStyle())
+    subtitleLabel.attributedText = NSAttributedString(
+      string: "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
+      attributes: generateTextStyle(smaller: true)
+    yinView.backgroundColor = UIColor.blackColor()
+  }
+  
+  required override init(coder aDecoder: NSCoder) {
+    fatalError("storyboards are incompatible with truth and beauty")
+  }
+  
+  override func viewDidLoad() {
+    super.viewDidLoad()
+    view.backgroundColor = UIColor.whiteColor()
+    view.addSubview(titleLabel)
+    view.addSubview(subtitleLabel)
+    view.addSubview(yinView)
+  }
+  
+  override func viewWillLayoutSubviews() {
+    titleLabel.sizeToFit()
+    titleLabel.top = 20
+    titleLabel.centerX = view.centerX
+    subtitleLabel.sizeToFit()
+    subtitleLabel.top = titleLabel.bottom + 8
+    subtitleLabel.centerX = view.centerX
+    yinView.top = view.height / 2
+    yinView.bottom2 = view.height
+  }
+  
+  private func generateTextStyle(smaller: Bool = false) -> [NSObject: AnyObject] {
+    return [
+      NSFontAttributeName: UIFont.systemFontOfSize(smaller ? 14 : 16),
+      NSForegroundColorAttributeName: UIColor.whiteColor()
+    ]
+  }
+}
+```
 
 #API Cheat Sheet
 
@@ -50,8 +106,18 @@ var left: CGFloat
 var size: CGSize
 var width: CGFloat
 var height: CGFloat
+
+// Alternate edges. Their names may change in the near future.
+var top2: CGFloat
+var right2: CGFloat
+var bottom2: CGFloat
+var left2: CGFloat
 ```
 
+The difference between alternate edges and normal edges require a bit of explaining. Imagine we have a view at position (0, 0) of size (100, 100) named *myView*. If we do `myView.right = 200`, then its position is now (200, 0) and its size remains unchaged. However, back when our view was located at (0, 0), if we had done `myView.right2 = 200`, then *myView* would have still been at (0, 0) but would have had a size of (200, 0).
+
+So basically, *setting a normal edge's position drags the whole view along with that edge but setting an alternative edge's position drags just that edge*. And don't worry if you, for example, try to drag a left edge past its view's right edge. Edge swapping is done automatically so you don't have to worry about.
+
 ###CALayer/UIView Methods
 
 Replace the word "layer" with "view" for the UIView methods.