Merge pull request #14 from acoomans/development

Updated README

README.md

@@ -1,20 +1,104 @@
 # AsyncDisplayKit
 
+---
+
 Welcome to the AsyncDisplayKit beta!  Documentation — including this README — will be fleshed out for the initial public release.  Until then, please direct questions and feedback to the [Paper Engineering Community](https://www.facebook.com/groups/551597518288687) group.
 
-## Installation
+---
 
-AsyncDisplayKit will be available on [CocoaPods](http://cocoapods.org/).  You can manually include it in your project's Podfile:
 
-```ruby
-pod 'AsyncDisplayKit', :git => 'git@github.com:facebook/AsyncDisplayKit.git'
-```
+AsyncDisplayKit is a library for smooth asynchronous user interfaces on iOS.
+
+UIKit traditionally only runs on the main thread. This includes expensive tasks like text sizing and rendering, as well as image decoding. 
+
+AsyncDisplayKit can handle all of the expensive parts asynchronously on a background thread, caching the values before actual views are created, and finally laying out views or layers efficiently on the main thread.
+
+AsyncDisplayKit uses display nodes to represent views and layers. The node API is designed to be as similar as possible to UIKit's. 
+
+
+## Install
+
+AsyncDisplayKit is available on [CocoaPods](http://cocoapods.org/).  You can manually include it in your project's Podfile:
+
+	pod 'AsyncDisplayKit', :git => 'git@github.com:facebook/AsyncDisplayKit.git'
+
+and run 
+
+	pod install
+
 
 ## Usage
 
-```objective-c
-#import <AsyncDisplayKit/AsyncDisplayKit.h>
-```
+Start by importing the header:
+
+	#import <AsyncDisplayKit/AsyncDisplayKit.h>
+
+An _ASDisplayNode_ is an abstraction over _UIView_ and _CALayer_ that allows you to perform all standard view- and layer-related tasks (layout, sizing calculations, view hierarchy management), moving expensive work off the main thread and with additional optimisations. More specifically, with node-based hierarchy, you can:
+
+- offload more-complex layout code to the background
+- enable layer-backing (on nodes that don't require touch handling)
+- enable subtree precompositing
+- create entire view hierarchies over multiple runloops
+
+and do all of this in advance and in the background, so complex content is ready to go by the time the user scrolls to it.
+
+The node API is designed to be as similar as possible to UIView.
+
+_ASDisplayNode_ can be allocated, initialized and its properties can be set all on a background thread.
+
+	dispatch_async(background_queue, ^{
+	
+		n = [[ASDisplayNode alloc] init];
+		n.frame = CGRectMake(0, 40, 100, 100);
+		n.backgroundColor = [UIColor greenColor];
+		
+	});
+
+Hierarchies can be created in a similar way as UIKit:
+
+	dispatch_async(background_queue, ^{
+		
+		s = [[ASDisplayNode alloc] init];
+		[n addSubNode:s];
+		
+	});
+
+A node may be backed by a view or layer, which must take place on the main thread. At this point, views may read their cached calculatedSize when performing layout.
+
+	dispatch_async(dispatch_get_main_queue(), ^{
+	
+		UIView *v = [node view];
+	
+		// You can now add it to the view hierarchy
+		[someView addSubview:v];
+
+		// The properties you set earlier will be preserved
+		// v.frame is {0, 40, 100, 100}
+		// v.backgroundColor is green
+	});
+	
+Besides _ASDisplayNode_, AsyncDisplayKit has UIKit equivalent classes:
+
+- _ASControlNode_: a UIButton equivalent
+- _ASTextNode_: a UITextView equivalent, with features like tap highlights, custom truncation strings, gradients, shadows, and tappable links.
+- _ASImageNode_: a UIImageView equivalent
+
+Node-aware UITableView and UICollectionView implementations are currently planned, but not yet implemented.
+
+
+## Subclassing
+
+To make your own nodes, start with the subclasses header
+
+	#import <AsyncDisplayKit/ASDisplayNode+Subclasses.h>
+
+The [header](https://github.com/facebook/AsyncDisplayKit/blob/master/AsyncDisplayKit/ASDisplayNode%2BSubclasses.h) contains possible and recommanded methods to override.
+
+
+## Documentation 
+
+See the [wiki](https://github.com/facebook/AsyncDisplayKit/wiki) for more details on use cases, performance, subclassing, bridged properties, sizing and layout, and UIKit divergence.
+
 
 ## Testing