Update README for v3 release

README.md

@@ -24,34 +24,46 @@ You can install the component in the following ways:
 Usage
 -----
 
-The ReflectionDocBlock component is designed to work in an identical fashion to
+In order to parse the DocBlock one needs a DocBlockFactory that can be
-PHP's own Reflection extension (http://php.net/manual/en/book.reflection.php).
+instantiated using its `createInstance` factory method like this:
 
-Parsing can be initiated by instantiating the
+```php
-`\phpDocumentor\Reflection\DocBlock()` class and passing it a string containing
+$factory  = \phpDocumentor\Reflection\DocBlockFactory::createInstance();
-a DocBlock (including asterisks) or by passing an object supporting the
+```
-`getDocComment()` method.
 
-> *Examples of objects having the `getDocComment()` method are the
+Then we can use the `create` method of the factory to interpret the DocBlock. 
-> `ReflectionClass` and the `ReflectionMethod` classes of the PHP
+Please note that it is also possible to provide a class that has the 
-> Reflection extension*
+`getDocComment()` method, such as an object of type `ReflectionClass`, the
+create method will read that if it exists.
 
-Example:
+```php
-
+$docComment = <<<DOCCOMMENT
-    $class = new ReflectionClass('MyClass');
+/**
-    $phpdoc = new \phpDocumentor\Reflection\DocBlock($class);
+ * This is an example of a summary.
-
-or
-
-    $docblock = <<<DOCBLOCK
-    /**
-     * This is a short description.
  *
-     * This is a *long* description.
+ * This is a Description. A Summary and Description are separated by either
-     *
+ * two subsequent newlines (thus a whiteline in between as can be seen in this
-     * @return void
+ * example), or when the Summary ends with a dot (`.`) and some form of
+ * whitespace.
  */
-    DOCBLOCK;
+DOCCOMMENT;
 
-    $phpdoc = new \phpDocumentor\Reflection\DocBlock($docblock);
+$docblock = $factory->create($docComment);
+```
+
+The `create` method will yield an object of type `\phpDocumentor\Reflection\DocBlock`
+whose methods can be queried as shown in the following example.
+
+```php
+// Should contain the summary for this DocBlock
+$summary = $docblock->getSummary();
+
+// Contains an object of type \phpDocumentor\Reflection\DocBlock\Description; 
+// you can either cast it to string or use the render method to get a string 
+// representation of the Description.
+$description = $docblock->getDescription();
+```
+
+> For more examples it would be best to review the scripts in the `/examples` 
+> folder.