refactored the development docs, which was badly needed especially since evaluate/dynamic.py doesn't contain a lot of functionality anymore.

docs/docs/development.rst

@@ -103,6 +103,15 @@ Evaluation Representation (evaluate/representation.py)
    FunctionExecution
    :parts: 1
 
+
+.. _name_resolution:
+
+Name resolution (evaluate/finder.py)
+++++++++++++++++++++++++++++++++++++
+
+.. automodule:: jedi.evaluate.finder
+
+
 .. _dev-api:
 
 API (api.py and api_classes.py)
@@ -115,7 +124,6 @@ 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.
 
 
-
 .. _core-extensions:
 
 Core Extensions
@@ -123,7 +131,8 @@ Core Extensions
 
 Core Extensions is a summary of the following topics:
 
-- :ref:`Dynamic Arrays & Function Parameters <dynamic>`
+- :ref:`Iterables & Dynamic Arrays <iterables>`
+- :ref:`Dynamic Parameters <dynamic>`
 - :ref:`Fast Parser <fast_parser>`
 - :ref:`Docstrings <docstrings>`
 - :ref:`Refactoring <refactoring>`
@@ -132,10 +141,21 @@ These topics are very important to understand what Jedi additionally does, but
 they could be removed from Jedi and Jedi would still work. But slower and
 without some features.
 
+.. _iterables:
+
+Iterables & Dynamic Arrays (evaluate/iterable.py)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To understand Python on a deeper level, |jedi| needs to understand some of the
+dynamic features of Python, however this probably the most complicated part:
+
+.. automodule:: jedi.evaluate.iterable
+
+
 .. _dynamic:
 
-Dynamic Arrays & Function Parameters (dynamic.py)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Parameter completion (evaluate/dynamic.py)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. automodule:: jedi.evaluate.dynamic
 

jedi/evaluate/dynamic.py

@@ -1,30 +1,4 @@
 """
-To understand Python on a deeper level, |jedi| needs to understand some of the
-dynamic features of Python, however this probably the most complicated part:
-
-- Array modifications (e.g. ``list.append``)
-- Parameter completion in functions
-- Flow checks (e.g. ``if isinstance(a, str)`` -> a is a str)
-
-Array modifications
-*******************
-
-If the content of an array (``set``/``list``) is wanted somewhere, the current
-module will be checked for appearances of ``arr.append``, ``arr.insert``, etc.
-If the ``arr`` name points to an actual array, the content will be added
-
-This can be really cpu intensive, as you can imagine. Because |jedi| has to
-follow **every** ``append``. However this works pretty good, because in *slow*
-cases, the recursion detector and other settings will stop this process.
-
-It is important to note that:
-
-1. Array modfications work only in the current module
-2. Only Array additions are being checked, ``list.pop``, etc. is being ignored.
-
-Parameter completion
-********************
-
 One of the really important features of |jedi| is to have an option to
 understand code like this::
 
@@ -38,19 +12,11 @@ that's what a human would expect.
 
 It works as follows:
 
-- A param is being encountered
+- |Jedi| sees a param
 - search for function calls named ``foo``
-- execute these calls and check the injected params. This work with a
-  ``ParamListener``.
-
-Flow checks
-***********
-
-Flow checks are not really mature. There's only a check for ``isinstance``.  It
-would check whether a flow has the form of ``if isinstance(a, type_or_tuple)``.
-Unfortunately every other thing is being ignored (e.g. a == '' would be easy to
-check for -> a is a string). There's big potential in these checks.
+- execute these calls and check the input. This work with a ``ParamListener``.
 """
+
 from jedi.parser import representation as pr
 from jedi import settings
 from jedi.evaluate import helpers

jedi/evaluate/finder.py

@@ -1,3 +1,16 @@
+"""
+Searcjing for names with given scope and name. This is very central in Jedi and
+Python. The name resolution is quite complicated with descripter,
+``__getattribute__``, ``__getattr__``, ``global``, etc.
+
+Flow checks
++++++++++++
+
+Flow checks are not really mature. There's only a check for ``isinstance``.  It
+would check whether a flow has the form of ``if isinstance(a, type_or_tuple)``.
+Unfortunately every other thing is being ignored (e.g. a == '' would be easy to
+check for -> a is a string). There's big potential in these checks.
+"""
 import copy
 import sys
 

jedi/evaluate/iterable.py

@@ -1,3 +1,25 @@
+"""
+Contains all classes and functions to deal with lists, dicts, generators and
+iterators in general.
+
+Array modifications
+*******************
+
+If the content of an array (``set``/``list``) is requested somewhere, the
+current module will be checked for appearances of ``arr.append``,
+``arr.insert``, etc.  If the ``arr`` name points to an actual array, the
+content will be added
+
+This can be really cpu intensive, as you can imagine. Because |jedi| has to
+follow **every** ``append`` and check wheter it's the right array. However this
+works pretty good, because in *slow* cases, the recursion detector and other
+settings will stop this process.
+
+It is important to note that:
+
+1. Array modfications work only in the current module.
+2. Jedi only checks Array additions; ``list.pop``, etc are ignored.
+"""
 import itertools
 
 from jedi import common