update docs, put reminder in there where to put LazyExpr in the future.

lib/python/Products/PageTemplates/DeferExpr.py

@@ -10,32 +10,16 @@
 # FOR A PARTICULAR PURPOSE
 #
 ##############################################################################
-"""Defer and Lazy expression handler
+"""Lazy expression handler
 
-defer expressions can be usesd for a design pattern called deferred evaluation.
-
-Example:
-
-    <div tal:define="xis defer:string:x is $x">
-      <p tal:repeat="x python:range(3)"
-         tal:content="xis"></p>
-    </div>
-
-Output:
-
-    <div>
-      <p>x is 0</p>
-      <p>x is 1</p>
-      <p>x is 2</p>
-    </div>
-    
-A lazy expressions is implemented in a similar way but has a different result. While
-a defer expression is evaluated every time it is used according to its context a lazy
-expression is evaluted only the first time it is used. Lazy expression are known
-under the name lazy initialization of variables, too. 
-A common use case for a lazy expression is a lazy binding of a costly expression.
-While one could call an expression only when it's required it makes sense to define
-it only one time when it could be used multiple times.
+A lazy expressions is implemented similarly to the defer expression
+but has a different result. While a defer expression is evaluated
+every time it is used according to its context a lazy expression is
+evaluted only the first time it is used. Lazy expression are known
+under the name lazy initialization of variables, too.  A common use
+case for a lazy expression is a lazy binding of a costly expression.
+While one could call an expression only when it's required it makes
+sense to define it only one time when it could be used multiple times.
 
 Example
 
@@ -46,11 +30,11 @@ Example
     </div>
 """
 from zope.tales.expressions import DeferWrapper, DeferExpr
-
-# lazy expression
-
 _marker = object()
 
+# TODO These should really be integrated into the Zope 3 ZPT
+# implementation (zope.tales)
+
 class LazyWrapper(DeferWrapper):
     """Wrapper for lazy: expression
     """