Clarified the messages documentation.

* Stated upfront that the messages framework is enabled by default.
* Explained why FallbackStorage, despites its unattractive name, is the
  default and likely the most efficient message storage class.

Thanks Jeremy Dunck for the review.

Closes #17026 (again).

docs/ref/contrib/messages.txt

@@ -5,14 +5,16 @@ The messages framework
 .. module:: django.contrib.messages
    :synopsis: Provides cookie- and session-based temporary message storage.
 
-Quite commonly in web applications, you may need to display a one-time
+Quite commonly in web applications, you need to display a one-time
-notification message (also know as "flash message") to the user after
+notification message (also known as "flash message") to the user after
-processing a form or some other types of user input. For this, Django provides
+processing a form or some other types of user input.
-full support for cookie- and session-based messaging, for both anonymous and
+
-authenticated users. The messages framework allows you to temporarily store
+For this, Django provides full support for cookie- and session-based
-messages in one request and retrieve them for display in a subsequent request
+messaging, for both anonymous and authenticated users. The messages framework
-(usually the next one). Every message is tagged with a specific ``level`` that
+allows you to temporarily store messages in one request and retrieve them for
-determines its priority (e.g., ``info``, ``warning``, or ``error``).
+display in a subsequent request (usually the next one). Every message is
+tagged with a specific ``level`` that determines its priority (e.g., ``info``,
+``warning``, or ``error``).
 
 Enabling messages
 =================
@@ -20,32 +22,27 @@ Enabling messages
 Messages are implemented through a :doc:`middleware </ref/middleware>`
 class and corresponding :doc:`context processor </ref/templates/api>`.
 
-To enable message functionality, do the following:
+The default ``settings.py`` created by ``django-admin.py startproject``
+already contains all the settings required to enable message functionality:
 
-* Edit the :setting:`MIDDLEWARE_CLASSES` setting and make sure
+* ``'django.contrib.messages'`` is in :setting:`INSTALLED_APPS`.
-  it contains ``'django.contrib.messages.middleware.MessageMiddleware'``.
 
-  If you are using a :ref:`storage backend <message-storage-backends>` that
+* :setting:`MIDDLEWARE_CLASSES` contains
-  relies on :doc:`sessions </topics/http/sessions>` (the default),
+  ``'django.contrib.sessions.middleware.SessionMiddleware'`` and
-  ``'django.contrib.sessions.middleware.SessionMiddleware'`` must be
+  ``'django.contrib.messages.middleware.MessageMiddleware'``.
-  enabled and appear before ``MessageMiddleware`` in your
+
+  The default :ref:`storage backend <message-storage-backends>` relies on
+  :doc:`sessions </topics/http/sessions>`. That's why ``SessionMiddleware``
+  must be enabled and appear before ``MessageMiddleware`` in
   :setting:`MIDDLEWARE_CLASSES`.
 
-* Edit the :setting:`TEMPLATE_CONTEXT_PROCESSORS` setting and make sure
+* :setting:`TEMPLATE_CONTEXT_PROCESSORS`   contains
-  it contains ``'django.contrib.messages.context_processors.messages'``.
+  ``'django.contrib.messages.context_processors.messages'``.
 
-* Add ``'django.contrib.messages'`` to your :setting:`INSTALLED_APPS`
+If you don't want to use messages, you can remove
-  setting
+``'django.contrib.messages'`` from your :setting:`INSTALLED_APPS`, the
-
+``MessageMiddleware`` line from :setting:`MIDDLEWARE_CLASSES`, and the
-The default ``settings.py`` created by ``django-admin.py startproject`` has
+``messages`` context processor from :setting:`TEMPLATE_CONTEXT_PROCESSORS`.
-``MessageMiddleware`` activated and the ``django.contrib.messages`` app
-installed. Also, the default value for :setting:`TEMPLATE_CONTEXT_PROCESSORS`
-contains ``'django.contrib.messages.context_processors.messages'``.
-
-If you don't want to use messages, you can remove the
-``MessageMiddleware`` line from :setting:`MIDDLEWARE_CLASSES`, the ``messages``
-context processor from :setting:`TEMPLATE_CONTEXT_PROCESSORS` and
-``'django.contrib.messages'`` from your :setting:`INSTALLED_APPS`.
 
 Configuring the message engine
 ==============================
@@ -56,34 +53,35 @@ Storage backends
 ----------------
 
 The messages framework can use different backends to store temporary messages.
-If the default FallbackStorage isn't suitable to your needs, you can change
-which backend is being used by adding a `MESSAGE_STORAGE`_ to your
-settings, referencing the module and class of the storage class. For
-example::
 
-    MESSAGE_STORAGE = 'django.contrib.messages.storage.cookie.CookieStorage'
+Django provides three built-in storage classes:
 
-The value should be the full path of the desired storage class.
+.. class:: django.contrib.messages.storage.session.SessionStorage
 
-Three storage classes are available:
+    This class stores all messages inside of the request's session. Therefore
+    it requires Django's ``contrib.sessions`` application.
 
-``'django.contrib.messages.storage.session.SessionStorage'``
+.. class:: django.contrib.messages.storage.cookie.CookieStorage
-    This class stores all messages inside of the request's session. It
-    requires Django's ``contrib.sessions`` application.
 
-``'django.contrib.messages.storage.cookie.CookieStorage'``
     This class stores the message data in a cookie (signed with a secret hash
     to prevent manipulation) to persist notifications across requests. Old
-    messages are dropped if the cookie data size would exceed 4096 bytes.
+    messages are dropped if the cookie data size would exceed 2048 bytes.
 
-``'django.contrib.messages.storage.fallback.FallbackStorage'``
+.. class:: django.contrib.messages.storage.fallback.FallbackStorage
-    This is the default storage class.
 
-    This class first uses CookieStorage for all messages, falling back to using
+    This class first uses ``CookieStorage``, and falls back to using
-    SessionStorage for the messages that could not fit in a single cookie.
+    ``SessionStorage`` for the messages that could not fit in a single cookie.
+    It also requires Django's ``contrib.sessions`` application.
 
-    Since it is uses SessionStorage, it also requires Django's
+    This behavior avoids writing to the session whenever possible. It should
-    ``contrib.sessions`` application.
+    provide the best performance in the general case.
+
+:class:`~django.contrib.messages.storage.fallback.FallbackStorage` is the
+default storage class. If it isn't suitable to your needs, you can select
+another storage class by setting `MESSAGE_STORAGE`_ to its full import path,
+for example::
+
+    MESSAGE_STORAGE = 'django.contrib.messages.storage.cookie.CookieStorage'
 
 To write your own storage class, subclass the ``BaseStorage`` class in
 ``django.contrib.messages.storage.base`` and implement the ``_get`` and
@@ -97,8 +95,8 @@ to that of the Python logging module. Message levels allow you to group
 messages by type so they can be filtered or displayed differently in views and
 templates.
 
-The built-in levels (which can be imported from ``django.contrib.messages``
+The built-in levels, which can be imported from ``django.contrib.messages``
-directly) are:
+directly, are:
 
 =========== ========
 Constant    Purpose