From b83c641057d6efcc2df9e066a9cc878202b04439 Mon Sep 17 00:00:00 2001
From: Dave Halter <davidhalter88@gmail.com>
Date: Mon, 4 Sep 2017 20:19:00 +0200
Subject: [PATCH] Better documentation for leafs/nodes.

---
 docs/_themes/flask/layout.html |  2 +-
 docs/docs/parser-tree.rst      | 20 ++++++++++++++++++--
 parso/tree.py                  | 29 ++++++++++++++++++++++++++---
 3 files changed, 45 insertions(+), 6 deletions(-)

diff --git a/docs/_themes/flask/layout.html b/docs/_themes/flask/layout.html
index e781a11..988d3de 100644
--- a/docs/_themes/flask/layout.html
+++ b/docs/_themes/flask/layout.html
@@ -7,7 +7,7 @@
   <link media="only screen and (max-device-width: 480px)" href="{{
     pathto('_static/small_flask.css', 1) }}" type= "text/css" rel="stylesheet" />
   <a href="https://github.com/davidhalter/jedi">
-    <img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_red_aa0000.png" alt="Fork me on GitHub">
+    <img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_red_aa0000.png" alt="Fork me">
   </a>
 {% endblock %}
 {%- block relbar2 %}{% endblock %}
diff --git a/docs/docs/parser-tree.rst b/docs/docs/parser-tree.rst
index 1924478..6635174 100644
--- a/docs/docs/parser-tree.rst
+++ b/docs/docs/parser-tree.rst
@@ -1,3 +1,5 @@
+.. include:: ../global.rst
+
 .. _parser-tree:
 
 Parser Tree
@@ -5,19 +7,33 @@ Parser Tree
 
 The parser tree is returned by calling :py:meth:`parso.Grammar.parse`.
 
-Parser Tree Base Class
-----------------------
+.. note:: Note that parso positions are always 1 based for lines and zero
+   based for columns. This means the first position in a file is (1, 0).
+
+Parser Tree Base Classes
+------------------------
 
 All nodes and leaves have these methods/properties:
 
+.. autoclass:: parso.tree.BaseNode
+    :show-inheritance:
+    :members:
+
+.. autoclass:: parso.tree.Leaf
+    :show-inheritance:
+    :members:
+
 .. autoclass:: parso.tree.NodeOrLeaf
     :members:
     :undoc-members:
+    :show-inheritance:
 
 
 Python Parser Tree
 ------------------
 
+.. currentmodule:: parso.python.tree
+
 .. automodule:: parso.python.tree
     :members:
     :undoc-members:
diff --git a/parso/tree.py b/parso/tree.py
index 135e319..a53eca4 100644
--- a/parso/tree.py
+++ b/parso/tree.py
@@ -22,6 +22,10 @@ class NodeOrLeaf(object):
     The base class for nodes and leaves.
     """
     __slots__ = ()
+    type = None
+    '''
+    The type is a string that typically matches the types of the grammar file.
+    '''
 
     def get_root_node(self):
         """
@@ -156,13 +160,27 @@ class NodeOrLeaf(object):
 
 
 class Leaf(NodeOrLeaf):
+    '''
+    Leafs are basically tokens with a better API. Leafs exactly know where they
+    were defined and what text preceeds them.
+    '''
     __slots__ = ('value', 'parent', 'line', 'column', 'prefix')
 
     def __init__(self, value, start_pos, prefix=''):
         self.value = value
+        '''
+        (: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
+        that is syntactically irrelevant for the syntax tree.
+        '''
         self.parent = None
+        '''
+        The parent :class:`BaseNode` of this leaf.
+        '''
 
     @property
     def start_pos(self):
@@ -220,9 +238,7 @@ class TypedLeaf(Leaf):
 class BaseNode(NodeOrLeaf):
     """
     The super class for all nodes.
-
-    If you create custom nodes, you will probably want to inherit from this
-    ``BaseNode``.
+    A node has children, a type and possibly a parent node.
     """
     __slots__ = ('children', 'parent')
     type = None
@@ -231,7 +247,14 @@ class BaseNode(NodeOrLeaf):
         for c in children:
             c.parent = self
         self.children = children
+        """
+        A list of :class:`NodeOrLeaf` child nodes.
+        """
         self.parent = None
+        '''
+        The parent :class:`BaseNode` of this leaf.
+        None if this is the root node.
+        '''
 
     @property
     def start_pos(self):