split also the parser / parser_representation docstring

jedi/parsing_representation.py

@@ -1,3 +1,25 @@
+"""
+If you know what an abstract syntax tree (ast) is, you'll see that this module
+is pretty much that. The classes represent syntax elements: ``Import``,
+``Function``.
+
+A very central class is ``Scope``. It is not used directly by the parser, but
+inherited. It's used by ``Function``, ``Class``, ``Flow``, etc. A ``Scope`` may
+have ``subscopes``, ``imports`` and ``statements``. The entire parser is based
+on scopes, because they also stand for indentation.
+
+One strange thing about the parser is that ``Array`` is two dimensional.  This
+has been caused by the fact that each array element can be defined by
+operations: ``[1, 2+33]``. So I chose to use a second dimension for ``2+33``,
+where each element would lie in the array like this: ``[2, '+', 33]``. In the
+future it might be useful to use Statements there, too (remove those crappy two
+dimensional arrays). This is also how ``Param`` works. Every single ``Param``
+is a ``Statement``.
+
+
+.. todo:: remove docstr params from Scope.__init__()
+"""
+
 import os
 import re
 import tokenize