Development doc fixes

docs/docs/development.rst

@@ -5,8 +5,8 @@ Jedi Development
 
 .. currentmodule:: jedi
 
-.. note:: This documentation is for Jedi developers, who want to improve Jedi
+.. note:: This documentation is for Jedi developers who want to improve Jedi
-    itself, but have just no idea how Jedi works. If you want to use Jedi for 
+    itself, but have no idea how Jedi works. If you want to use Jedi for 
     your IDE, look at the `plugin api <plugin-api.html>`_.
 
 
@@ -17,13 +17,13 @@ This page tries to address the fundamental demand for documentation of the
 |jedi| interals. Understanding a dynamic language is a complex task. Especially
 because type inference in Python can be a very recursive task. Therefore |jedi|
 couldn't get rid of complexity. I know that **simple is better than complex**,
-but unfortunately it requires sometimes complex solutions to understand complex
+but unfortunately it sometimes requires complex solutions to understand complex
 systems.
 
 Since most of the Jedi internals have been written by me (David Halter), this
-introduction will be written mostly by me, because no one else understands how
+introduction will be written mostly by me, because no one else understands to
-Jedi works. Actually this is also the reason for exactly this part of the
+the same level how Jedi works. Actually this is also the reason for exactly this
-documentation. To make multiple people able to edit the Jedi core.
+part of the documentation. To make multiple people able to edit the Jedi core.
 
 In five chapters I'm trying to describe the internals of |jedi|:
 
@@ -46,8 +46,8 @@ The core of Jedi consists of three parts:
 - :ref:`API <dev-api>`
 
 Most people are probably interested in :ref:`code evaluation <evaluate>`,
-because that's where all the magic happens. I need to introduce the
+because that's where all the magic happens. I need to introduce the :ref:`parser
-:ref:`parser <parsing>` first, because evaluate uses it extensively.
+<parsing>` first, because :mod:`evaluate` uses it extensively.
 
 .. _parsing:
 
@@ -68,11 +68,11 @@ Evaluation of python code (evaluate.py)
 API (api.py and api_classes.py)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The API has been designed to be as usable as possible. The API documentation
+The API has been designed to be as easy to use as possible. The API
-can be found `here <plugin-api.html>`_. The API itself contains little code
+documentation can be found `here <plugin-api.html>`_. The API itself contains
-that needs to be mentioned here. Generally I'm trying to be conservative with
+little code that needs to be mentioned here. Generally I'm trying to be
-the API.  I'd rather not add new API features if they are not necessary,
+conservative with the API.  I'd rather not add new API features if they are not
-because it's much harder to deprecate stuff than to add it later.
+necessary, because it's much harder to deprecate stuff than to add it later.
 
 
 

jedi/evaluate.py

@@ -28,9 +28,9 @@ make an example:
 >>> import datetime
 >>> datetime.date.toda# <-- cursor here
 
-First of it all, this module doesn't care about completion. It really just
+First of all, this module doesn't care about completion. It really just cares
-cares about ``datetime.date``. At the end of the procedure
+about ``datetime.date``. At the end of the procedure ``follow_statement`` will
-``follow_statement`` will return the ``datetime`` class.
+return the ``datetime`` class.
 
 To *visualize* this (simplified):
 
@@ -68,7 +68,7 @@ want. This module has been tested by about 600 tests. Don't be afraid to break
 something. The tests are good enough.
 
 I need to mention now that this recursive approach is really good because it
-only *executes* what needs to be *executed*. All the statements and modules
+only *evaluates* what needs to be *evaluated*. All the statements and modules
 that are not used are just being ignored. It's a little bit similar to the
 backtracking algorithm.
 

jedi/parsing.py

@@ -6,10 +6,11 @@ This module is split in two parts:
 
 The ``Parser`` tries to represent the available Python code in an easy to read
 format. The Python module ``tokenize`` is a very important part in the
-``Parser``, because it splits the code into different words. Sometimes it looks
+``Parser``, because it splits the code into different words (tokens).
-a bit messy. Sorry for that! You might ask now: "Why didn't you use the ``ast``
+Sometimes it looks a bit messy. Sorry for that! You might ask now: "Why didn't
-module for this? Well, ``ast`` does a very good job understanding proper Python
+you use the ``ast`` module for this? Well, ``ast`` does a very good job
-code, but fails to work if there's only one single line of broken code.
+understanding proper Python code, but fails to work as soon as there's a single
+line of broken code.
 
 The classes are not very hard to understand. They are being named like you
 would call them: ``Import``, ``Class``, etc.