Document issues about our internal tree.

README.rst

@@ -42,7 +42,7 @@ Known Issues
 ============
 
 - `async`/`await` are already used as keywords in Python3.6.
-- `from __future__ import print_function` is not supported,
+- `from __future__ import print_function` is not ignored.
 
 Testing
 =======

docs/docs/parser-tree.rst

@@ -13,7 +13,8 @@ The parser tree is returned by calling :py:meth:`parso.Grammar.parse`.
 Parser Tree Base Classes
 ------------------------
 
-All nodes and leaves have these methods/properties:
+Generally there are two types of classes you will deal with:
+:py:class:`parso.tree.Leaf` and :py:class:`parso.tree.BaseNode`.
 
 .. autoclass:: parso.tree.BaseNode
     :show-inheritance:
@@ -23,6 +24,8 @@ All nodes and leaves have these methods/properties:
     :show-inheritance:
     :members:
 
+All nodes and leaves have these methods/properties:
+
 .. autoclass:: parso.tree.NodeOrLeaf
     :members:
     :undoc-members:

parso/python/tree.py

@@ -12,7 +12,7 @@ to deal with a Python syntax tree.
 
 By using :py:meth:`parso.tree.NodeOrLeaf.get_code` on a module, you can get
 back the 1-to-1 representation of the input given to the parser. This is
-important if you are using refactoring.
+important if you want to refactor a parser tree.
 
 >>> from parso import parse
 >>> parser = parse('import os')
@@ -25,6 +25,21 @@ Any subclasses of :class:`Scope`, including :class:`Module` has an attribute
 
 >>> list(module.iter_imports())
 [<ImportName: import os@1,0>]
+
+Changes to the Python Grammar
+-----------------------------
+
+A few things have changed when looking at Python grammar files:
+
+- :class:`Param` does not exist in Python grammar files. It is essentially a
+  part of a ``parameters`` node.  |parso| splits it up to make it easier to
+  analyse parameters. However this just makes it easier to deal with the syntax
+  tree, it doesn't actually change the valid syntax.
+- A few nodes like `lambdef` and `lambdef_nocond` have been merged in the
+  syntax tree to make it easier to do deal with them.
+
+Parser Tree Classes
+-------------------
 """
 
 import re

parso/tree.py

@@ -169,12 +169,12 @@ class Leaf(NodeOrLeaf):
     def __init__(self, value, start_pos, prefix=''):
         self.value = value
         '''
-        (:py:func:`str`) The value of the current token.
+        :py:func:`str` The value of the current token.
         '''
         self.start_pos = start_pos
         self.prefix = prefix
         '''
-        (:py:func:`str`) Typically a mixture of whitespace and comments. Stuff
+        :py:func:`str` Typically a mixture of whitespace and comments. Stuff
         that is syntactically irrelevant for the syntax tree.
         '''
         self.parent = None