From a0f07c90e89501919ee3845d9a8a85c2c8a4aafc Mon Sep 17 00:00:00 2001 From: Danilo Bargen Date: Tue, 5 Feb 2013 11:31:05 +0100 Subject: [PATCH] Development doc fixes --- docs/docs/development.rst | 26 +++++++++++++------------- jedi/evaluate.py | 8 ++++---- jedi/parsing.py | 9 +++++---- 3 files changed, 22 insertions(+), 21 deletions(-) diff --git a/docs/docs/development.rst b/docs/docs/development.rst index 8d473d65..c37f8c8c 100644 --- a/docs/docs/development.rst +++ b/docs/docs/development.rst @@ -5,8 +5,8 @@ Jedi Development .. currentmodule:: 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 +.. note:: This documentation is for Jedi developers who want to improve Jedi + itself, but have no idea how Jedi works. If you want to use Jedi for your IDE, look at the `plugin api `_. @@ -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 -Jedi works. Actually this is also the reason for exactly this part of the -documentation. To make multiple people able to edit the Jedi core. +introduction will be written mostly by me, because no one else understands to +the same level how Jedi works. Actually this is also the reason for exactly this +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 ` Most people are probably interested in :ref:`code evaluation `, -because that's where all the magic happens. I need to introduce the -:ref:`parser ` first, because evaluate uses it extensively. +because that's where all the magic happens. I need to introduce the :ref:`parser +` 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 -can be found `here `_. The API itself contains little code -that needs to be mentioned here. Generally I'm trying to be conservative with -the API. I'd rather not add new API features if they are not necessary, -because it's much harder to deprecate stuff than to add it later. +The API has been designed to be as easy to use as possible. The API +documentation can be found `here `_. The API itself contains +little code that needs to be mentioned here. Generally I'm trying to be +conservative with the API. I'd rather not add new API features if they are not +necessary, because it's much harder to deprecate stuff than to add it later. diff --git a/jedi/evaluate.py b/jedi/evaluate.py index 26e25bbc..7bfbe7a7 100644 --- a/jedi/evaluate.py +++ b/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 -cares about ``datetime.date``. At the end of the procedure -``follow_statement`` will return the ``datetime`` class. +First of all, this module doesn't care about completion. It really just cares +about ``datetime.date``. At the end of the procedure ``follow_statement`` will +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. diff --git a/jedi/parsing.py b/jedi/parsing.py index 82b7e5f9..704ca3d0 100644 --- a/jedi/parsing.py +++ b/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 -a bit messy. Sorry for that! You might ask now: "Why didn't you use the ``ast`` -module for this? Well, ``ast`` does a very good job understanding proper Python -code, but fails to work if there's only one single line of broken code. +``Parser``, because it splits the code into different words (tokens). +Sometimes it looks a bit messy. Sorry for that! You might ask now: "Why didn't +you use the ``ast`` module for this? Well, ``ast`` does a very good job +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.