Review documentation for the new extensions API.

1 files changed, 13 insertions, 10 deletions

diff --git a/doc/extending.rst b/doc/extending.rst
index da3b4e6..946d011 100644
--- a/doc/extending.rst
+++ b/doc/extending.rst
@@ -1,28 +1,31 @@
 Extending Astroid Syntax Tree
 =============================
 
-Sometimes Astroid will miss some potentially important information you may wish
-you add, as content of the standard library `hashlib` module. In some other
-cases, you may want to customize the way inference work, for instance to explain
-Astroid that `collections.namedtuple` is returning a class with some known
+Sometimes Astroid will miss some potentially important information
+users may wish to add, for instance with the standard library
+`hashlib` module. In some other cases, users may want to customize the
+way inference works, for instance to explain Astroid that calls to
+`collections.namedtuple` are returning a class with some known
 attributes.
 
-The good news is that you can do it using the transformation API. You'll find
-examples in the `brain/` subdirectory. Those come from the `pylint-brain`_ project.
+Modifications in the AST are now possible using the using the generic
+transformation API. You can find examples in the `brain/`
+subdirectory, which are taken from the the `pylint-brain`_ project.
 
 Transformation functions are registered using the `register_transform` method of
 the Astroid manager:
 
 .. automethod:: astroid.manager.AstroidManager.register_transform
 
-You may want to use :class:`astroid.AsStringRegexpPredicate` predicate objects
-to filter on the `as_string` representation of the node.
+To add filtering based on the `as_string` representation of the node
+in addition to the type, the :class:`astroid.AsStringRegexpPredicate`
+predicate object can be used.
 
 .. autoclass:: astroid.AsStringRegexpPredicate
 
 Last but not least, the :func:`inference_tip` function is there to register
-custom inference function.
+a custom inference function.
 
 .. autofunction:: astroid.inference_tip
 
-.. _`pylint-brain`: https://bitbucket.org/logilab/pylint-brain
\ No newline at end of file
+.. _`pylint-brain`: https://bitbucket.org/logilab/pylint-brain