better docstrings, and added missing ZPL to ustr.py

lib/python/DocumentTemplate/cDocumentTemplate.c

@@ -12,7 +12,7 @@
  ****************************************************************************/
 static char cDocumentTemplate_module_documentation[] = 
 ""
-"\n$Id: cDocumentTemplate.c,v 1.44 2002/03/27 10:14:02 htrd Exp $"
+"\n$Id: cDocumentTemplate.c,v 1.45 2002/04/25 12:45:11 htrd Exp $"
 ;
 
 #include "ExtensionClass.h"
@@ -930,9 +930,9 @@ static struct PyMethodDef Module_Level__methods[] = {
   {"render_blocks", (PyCFunction)render_blocks,	METH_VARARGS,
    ""},
   {"join_unicode", (PyCFunction)join_unicode,	METH_VARARGS,
-   "join a list of plain strings into a single plain string,"
-   "a list of unicode strings into a single unicode strings,"
-   "or a list containing a mix into a single unicode string with"
+   "join a list of plain strings into a single plain string,\n"
+   "a list of unicode strings into a single unicode strings,\n"
+   "or a list containing a mix into a single unicode string with\n"
    "the plain strings converted from latin-1"},
   {"safe_callable", (PyCFunction)safe_callable,	METH_VARARGS,
    "callable() with a workaround for a problem with ExtensionClasses\n"

lib/python/DocumentTemplate/ustr.py

+##############################################################################
+#
+# Copyright (c) 2001 Zope Corporation and Contributors. All Rights Reserved.
+#
+# This software is subject to the provisions of the Zope Public License,
+# Version 2.0 (ZPL).  A copy of the ZPL should accompany this distribution.
+# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
+# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
+# FOR A PARTICULAR PURPOSE
+#
+##############################################################################
+
 from types import StringType, UnicodeType, InstanceType
 
 nasty_exception_str = Exception.__str__.im_func
 
 def ustr(v):
-    """convert an object to a plain string or unicode string
+    """Convert any object to a plain string or unicode string,
+    minimising the chance of raising a UnicodeError. This
+    even works with uncooperative objects like Exceptions
     """
     string_types = (StringType,UnicodeType)
     if type(v) in string_types: