Reworded docstrings and settings documentation from [1068]

git-svn-id: http://code.djangoproject.com/svn/django/trunk@1098 bcc190cf-cafb-0310-a4f2-bffc1f526a37

django/core/template/__init__.py

@@ -236,15 +236,12 @@ class Parser:
 
 class TokenParser:
     """
-    You need to subclass this class and implement the
+    Subclass this and implement the top() method to parse a template line. When
-    top method to parse your template line. When instantiating
+    instantiating the parser, pass in the line from the Django template parser.
-    the parser, you pass in the line from the django template
-    parser.
 
-    If your tag needs to know what tag name it was called with,
+    The parser's "tagname" instance-variable stores the name of the tag that
-    you find it in the tagname instance variable of the parser.
+    the filter was called with.
     """
-
     def __init__(self, subject):
         self.subject = subject
         self.pointer = 0
@@ -252,31 +249,21 @@ class TokenParser:
         self.tagname = self.tag()
 
     def top(self):
-        """
+        "Overload this method to do the actual parsing and return the result."
-        You need to overload this method to do the actual parsing
-        and return the result.
-        """
         raise NotImplemented
 
     def more(self):
-        """
+        "Returns True if there is more stuff in the tag."
-        This returns True if there is more stuff in the tag.
-        """
         return self.pointer < len(self.subject)
 
     def back(self):
-        """
+        "Undoes the last microparser. Use this for lookahead and backtracking."
-        This method undos the last microparser. This can be
-        used for lookahead and backtracking.
-        """
         if not len(self.backout):
             raise TemplateSyntaxError, "back called without some previous parsing"
         self.pointer = self.backout.pop()
 
     def tag(self):
-        """
+        "A microparser that just returns the next tag from the line."
-        This microparser just returns the next tag from the line.
-        """
         subject = self.subject
         i = self.pointer
         if i >= len(subject):
@@ -292,21 +279,18 @@ class TokenParser:
         return s
 
     def value(self):
-        """
+        "A microparser that parses for a value: some string constant or variable name."
-        This microparser parses for a value - some string constant or
-        variable name.
-        """
         subject = self.subject
         i = self.pointer
         if i >= len(subject):
-            raise TemplateSyntaxError, "searching for value expected another value, found end of string: %s" % subject
+            raise TemplateSyntaxError, "Searching for value. Expected another value but found end of string: %s" % subject
         if subject[i] in ('"', "'"):
             p = i
             i += 1
             while i < len(subject) and subject[i] != subject[p]:
                 i += 1
             if i >= len(subject):
-                raise TemplateSyntaxError, "searching for value, unexpected end of string in column %d: %s" % subject
+                raise TemplateSyntaxError, "Searching for value. Unexpected end of string in column %d: %s" % subject
             i += 1
             res = subject[p:i]
             while i < len(subject) and subject[i] in (' ', '\t'):
@@ -326,18 +310,19 @@ class TokenParser:
             return s
 
 class FilterParser:
-    """Parse a variable token and its optional filters (all as a single string),
+    """
-       and return a list of tuples of the filter name and arguments.
+    Parses a variable token and its optional filters (all as a single string),
-       Sample:
+    and return a list of tuples of the filter name and arguments.
-            >>> token = 'variable|default:"Default value"|date:"Y-m-d"'
+    Sample:
-            >>> p = FilterParser(token)
+        >>> token = 'variable|default:"Default value"|date:"Y-m-d"'
-            >>> p.filters
+        >>> p = FilterParser(token)
-            [('default', 'Default value'), ('date', 'Y-m-d')]
+        >>> p.filters
-            >>> p.var
+        [('default', 'Default value'), ('date', 'Y-m-d')]
-            'variable'
+        >>> p.var
+        'variable'
 
-        This class should never be instantiated outside of the
+    This class should never be instantiated outside of the
-        get_filters_from_token helper function.
+    get_filters_from_token helper function.
     """
     def __init__(self, s):
         self.s = s
@@ -346,8 +331,8 @@ class FilterParser:
         self.filters = []
         self.current_filter_name = None
         self.current_filter_arg = None
-        # First read the variable part - decide on wether we need
+        # First read the variable part. Decide whether we need to parse a
-        # to parse a string or a variable by peeking into the stream
+        # string or a variable by peeking into the stream.
         if self.peek_char() in ('_', '"', "'"):
             self.var = self.read_constant_string_token()
         else:
@@ -378,15 +363,17 @@ class FilterParser:
             self.current = None
 
     def read_constant_string_token(self):
-        """Read a constant string that must be delimited by either "
+        """
-        or ' characters. The string is returned with it's delimiters."""
+        Reads a constant string that must be delimited by either " or '
+        characters. The string is returned with its delimiters.
+        """
         val = ''
         qchar = None
         i18n = False
         self.next_char()
         if self.current == '_':
             i18n = True
-            self.next_char() 
+            self.next_char()
             if self.current != '(':
                 raise TemplateSyntaxError, "Bad character (expecting '(') '%s'" % self.current
             self.next_char()
@@ -409,8 +396,10 @@ class FilterParser:
         return val
 
     def read_alphanumeric_token(self):
-        """Read a variable name or filter name, which are continuous strings of
+        """
-        alphanumeric characters + the underscore"""
+        Reads a variable name or filter name, which are continuous strings of
+        alphanumeric characters + the underscore.
+        """
         var = ''
         while 1:
             self.next_char()

django/core/template/defaulttags.py

@@ -2,10 +2,7 @@
 
 from django.core.template import Node, NodeList, Template, Context, resolve_variable, resolve_variable_with_filters, get_filters_from_token, registered_filters
 from django.core.template import TemplateSyntaxError, VariableDoesNotExist, BLOCK_TAG_START, BLOCK_TAG_END, VARIABLE_TAG_START, VARIABLE_TAG_END, register_tag
-from django.utils import translation
-
 import sys
-import re
 
 class CommentNode(Node):
     def render(self, context):
@@ -531,12 +528,10 @@ def do_if(parser, token):
         {% endif %}
 
         {% if not athlete_list or coach_list %}
-            There are no athletes or there are some coaches (OK, so
+            There are no athletes, or there are some coaches.
-            writing English translations of boolean logic sounds
-            stupid; it's not my fault).
         {% endif %}
 
-    For simplicity, ``if`` tags do not allow ``and`` clauses; use nested ``if``
+    For simplicity, ``if`` tags do not allow ``and`` clauses. Use nested ``if``
     tags instead::
 
         {% if athlete_list %}

django/utils/functional.py

@@ -4,24 +4,17 @@ def curry(*args, **kwargs):
     return _curried
 
 def lazy(func, *resultclasses):
-
     """
-    lazy turns any callable passed in into a lazy evaluated callable.
+    Turns any callable into a lazy evaluated callable. You need to give result
-    you need to give result classes or types - at least one is needed
+    classes or types -- at least one is needed so that the automatic forcing of
-    so that the automatic forcing of the lazy evaluation code is
+    the lazy evaluation code is triggered. Results are not memoized; the
-    triggered. Results are not memoized - the function is evaluated
+    function is evaluated on every access.
-    on every access.
     """
-
     class __proxy__:
-    
+        # This inner class encapsulates the code that should be evaluated
-        """
+        # lazily. On calling of one of the magic methods it will force
-        This inner class encapsulates the code that should be evaluated
+        # the evaluation and store the result. Afterwards, the result
-        lazyly. On calling of one of the magic methods it will force
+        # is delivered directly. So the result is memoized.
-        the evaluation and store the result - afterwards the result
-        is delivered directly. So the result is memoized.
-        """
-
         def __init__(self, args, kw):
            self.__func = func
            self.__args = args
@@ -31,35 +24,23 @@ def lazy(func, *resultclasses):
                self.__dispatch[resultclass] = {}
                for (k, v) in resultclass.__dict__.items():
                    setattr(self, k, self.__promise__(resultclass, k, v))
-	
+
         def __promise__(self, klass, funcname, func):
-        
+            # Builds a wrapper around some magic method and registers that magic
-            """
+            # method for the given type and method name.
-            This function builds a wrapper around some magic method and
-            registers that magic method for the given type and methodname.
-            """
-    
             def __wrapper__(*args, **kw):
-                """
+                # Automatically triggers the evaluation of a lazy value and
-                This wrapper function automatically triggers the evaluation of
+                # applies the given magic method of the result type.
-                a lazy value. It then applies the given magic method of the
-                result type.
-                """
                 res = self.__func(*self.__args, **self.__kw)
                 return self.__dispatch[type(res)][funcname](res, *args, **kw)
-  
+
             if not self.__dispatch.has_key(klass):
                 self.__dispatch[klass] = {}
             self.__dispatch[klass][funcname] = func
             return __wrapper__
-  
+
     def __wrapper__(*args, **kw):
-        """
+        # Creates the proxy object, instead of the actual value.
-        This wrapper function just creates the proxy object that is returned
-        instead of the actual value.
-        """
         return __proxy__(args, kw)
 
     return __wrapper__
-
-

docs/settings.txt

@@ -355,12 +355,13 @@ See http://www.thaiopensource.com/relaxng/jing.html .
 LANGUAGE_CODE
 -------------
 
-Default: ``'en'``
+Default: ``'en-us'``
 
-A string representing the language code for this installation. This should
+A string representing the language code for this installation. This should be
-be in locale format, that's 'en_US' for us-english. If you want to send
+in standard language format. For example, U.S. English is ``"en-us"``. See the
-out the language in your HTML code, use the LANGUAGE_CODE attribute of the
+`internationalization docs`_.
-request, instead, as the chosen language will depend on the browsers settings.
+
+.. _internationalization docs: http://www.djangoproject.com/documentation/i18n/
 
 MANAGERS
 --------