[1.5.x] Fixed #20687 -- Added documentation for django.core.signing API.

Thanks Baptiste Mispelon for the suggestion.

Backport of c5bc98d from master.

django/core/signing.py

@@ -195,6 +195,10 @@ def sign(self, value):
         return super(TimestampSigner, self).sign(value)
 
     def unsign(self, value, max_age=None):
+        """
+        Retrieve original value and check it wasn't signed more
+        than max_age seconds ago.
+        """
         result =  super(TimestampSigner, self).unsign(value)
         value, timestamp = result.rsplit(self.sep, 1)
         timestamp = baseconv.base62.decode(timestamp)

docs/topics/signing.txt

@@ -39,8 +39,6 @@ generate their own signed values.
 Using the low-level API
 =======================
 
-.. class:: Signer
-
 Django's signing methods live in the ``django.core.signing`` module.
 To sign a value, first instantiate a ``Signer`` instance::
 
@@ -76,6 +74,11 @@ generate signatures. You can use a different secret by passing it to the
     >>> value
     'My string:EkfQJafvGyiofrdGnuthdxImIJw'
 
+.. class:: Signer(key=None, sep=':', salt=None)
+
+    Returns a signer which uses ``key`` to generate signatures and ``sep``
+    to separate values.
+
 Using the salt argument
 -----------------------
 
@@ -107,8 +110,6 @@ secret.
 Verifying timestamped values
 ----------------------------
 
-.. class:: TimestampSigner
-
 ``TimestampSigner`` is a subclass of :class:`~Signer` that appends a signed
 timestamp to the value. This allows you to confirm that a signed value was
 created within a specified period of time::
@@ -126,6 +127,17 @@ created within a specified period of time::
     >>> signer.unsign(value, max_age=20)
     u'hello'
 
+.. class:: TimestampSigner(key=None, sep=':', salt=None)
+
+    .. method:: sign(value)
+
+        Sign ``value`` and append current timestamp to it.
+
+    .. method:: unsign(value, max_age=None)
+
+        Checks if ``value`` was signed less than ``max_age`` seconds ago,
+        otherwise raises ``SignatureExpired``.
+
 Protecting complex data structures
 ----------------------------------
 
@@ -144,8 +156,10 @@ to execute arbitrary commands by exploiting the pickle format.::
 
 .. function:: dumps(obj, key=None, salt='django.core.signing', compress=False)
 
-    Returns URL-safe, sha1 signed base64 compressed JSON string.
+    Returns URL-safe, sha1 signed base64 compressed JSON string. Serialized
+    object is signed using :class:`~TimestampSigner`.
 
 .. function:: loads(string, key=None, salt='django.core.signing', max_age=None)
 
-    Reverse of dumps(), raises ``BadSignature`` if signature fails.
+    Reverse of ``dumps()``, raises ``BadSignature`` if signature fails.
+    Checks ``max_age`` (in seconds) if given.