From 032c7563c48d545640100bd98c64b9ecb50c9ade Mon Sep 17 00:00:00 2001
From: Dave Halter <davidhalter88@gmail.com>
Date: Mon, 4 Sep 2017 20:54:48 +0200
Subject: [PATCH] Document issues about our internal tree.

---
 README.rst                |  2 +-
 docs/docs/parser-tree.rst |  5 ++++-
 parso/python/tree.py      | 17 ++++++++++++++++-
 parso/tree.py             |  4 ++--
 4 files changed, 23 insertions(+), 5 deletions(-)

diff --git a/README.rst b/README.rst
index 2b3b4e0..34950b1 100644
--- a/README.rst
+++ b/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
 =======
diff --git a/docs/docs/parser-tree.rst b/docs/docs/parser-tree.rst
index 6635174..6eb2006 100644
--- a/docs/docs/parser-tree.rst
+++ b/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:
diff --git a/parso/python/tree.py b/parso/python/tree.py
index 614079c..6b22d26 100644
--- a/parso/python/tree.py
+++ b/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
diff --git a/parso/tree.py b/parso/tree.py
index a53eca4..b098402 100644
--- a/parso/tree.py
+++ b/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