diff --git a/joy/joy.py b/joy/joy.py
index dbad922..ceb90be 100644
--- a/joy/joy.py
+++ b/joy/joy.py
@@ -35,12 +35,15 @@ from .utils.pretty_print import TracePrinter
 
 
 def joy(stack, expression, dictionary, viewer=None):
-  '''Evaluate the Joy expression on the stack.
+  '''Evaluate a Joy expression on a stack.
 
-  The basic joy() function is quite straightforward.  It iterates through a
-  sequence of terms which are either literals (strings, numbers, sequences)
-  or functions.  Literals are put onto the stack and functions are
-  executed.
+  This function iterates through a sequence of terms which are either
+  literals (strings, numbers, sequences of terms) or function symbols.
+  Literals are put onto the stack and functions are looked up in the
+  disctionary and executed.
+
+  The viewer is a function that is called with the stack and expression
+  on every iteration, its return value is ignored.
 
   :param stack stack: The stack.
   :param stack expression: The expression to evaluate.
diff --git a/joy/parser.py b/joy/parser.py
index 350bc9c..3307c6b 100644
--- a/joy/parser.py
+++ b/joy/parser.py
@@ -26,11 +26,14 @@ by the fact that they are not Symbol objects.
 
 A crude grammar::
 
-  joy = term*
-  term = int | float | string | '[' joy ']' | function
-
-A Joy expression is a sequence of zero or more terms
+    joy = term*
+    term = int | float | string | '[' joy ']' | symbol
 
+A Joy expression is a sequence of zero or more terms.  A term is a
+literal value (integer, float, string, or Joy expression) or a function
+symbol.  Function symbols are unquoted strings and cannot contain square
+brackets.   Terms must be separated by blanks, which can be omitted
+around square brackets.
 
 '''
 #TODO: explain the details of float lits and strings.