From b785927b442d1e4b59f2afa40729a4ca1a7ed3ab Mon Sep 17 00:00:00 2001 From: Kevin Christopher Henry Date: Thu, 11 Aug 2016 07:05:16 -0400 Subject: [PATCH] Documented the cache_control() decorator. --- docs/topics/cache.txt | 25 ++++++++++++++----------- docs/topics/http/decorators.txt | 7 +++++++ 2 files changed, 21 insertions(+), 11 deletions(-) diff --git a/docs/topics/cache.txt b/docs/topics/cache.txt index bb43dd31db..d8c43ad196 100644 --- a/docs/topics/cache.txt +++ b/docs/topics/cache.txt @@ -496,9 +496,10 @@ If a view sets its own cache expiry time (i.e. it has a ``max-age`` section in its ``Cache-Control`` header) then the page will be cached until the expiry time, rather than :setting:`CACHE_MIDDLEWARE_SECONDS`. Using the decorators in ``django.views.decorators.cache`` you can easily set a view's expiry time -(using the ``cache_control`` decorator) or disable caching for a view (using -the ``never_cache`` decorator). See the `using other headers`__ section for -more on these decorators. +(using the :func:`~django.views.decorators.cache.cache_control` decorator) or +disable caching for a view (using the +:func:`~django.views.decorators.cache.never_cache` decorator). See the +`using other headers`__ section for more on these decorators. .. _i18n-cache-key: @@ -1139,7 +1140,8 @@ public cache. So Web applications need a way to tell caches which data is private and which is public. The solution is to indicate a page's cache should be "private." To do this in -Django, use the ``cache_control`` view decorator. Example:: +Django, use the :func:`~django.views.decorators.cache.cache_control` view +decorator. Example:: from django.views.decorators.cache import cache_control @@ -1155,9 +1157,9 @@ exclusive. The decorator ensures that the "public" directive is removed if "private" should be set (and vice versa). An example use of the two directives would be a blog site that offers both private and public entries. Public entries may be cached on any shared cache. The following code uses -:func:`django.utils.cache.patch_cache_control`, the manual way to modify the -cache control header (it is internally called by the ``cache_control`` -decorator):: +:func:`~django.utils.cache.patch_cache_control`, the manual way to modify the +cache control header (it is internally called by the +:func:`~django.views.decorators.cache.cache_control` decorator):: from django.views.decorators.cache import patch_cache_control from django.views.decorators.vary import vary_on_cookie @@ -1187,7 +1189,8 @@ directive:: (If you *do* use the caching middleware, it already sets the ``max-age`` with the value of the :setting:`CACHE_MIDDLEWARE_SECONDS` setting. In that case, -the custom ``max_age`` from the ``cache_control`` decorator will take +the custom ``max_age`` from the +:func:`~django.views.decorators.cache.cache_control` decorator will take precedence, and the header values will be merged correctly.) Any valid ``Cache-Control`` response directive is valid in ``cache_control()``. @@ -1203,9 +1206,9 @@ The full list of known directives can be found in the `IANA registry`_ .. _IANA registry: http://www.iana.org/assignments/http-cache-directives/http-cache-directives.xhtml If you want to use headers to disable caching altogether, -:func:`django.views.decorators.cache.never_cache` is a view decorator that adds -headers to ensure the response won't be cached by browsers or other caches. -Example:: +:func:`~django.views.decorators.cache.never_cache` is a view decorator that +adds headers to ensure the response won't be cached by browsers or other +caches. Example:: from django.views.decorators.cache import never_cache diff --git a/docs/topics/http/decorators.txt b/docs/topics/http/decorators.txt index 483bd4c97a..55676c4888 100644 --- a/docs/topics/http/decorators.txt +++ b/docs/topics/http/decorators.txt @@ -106,6 +106,13 @@ Caching The decorators in :mod:`django.views.decorators.cache` control server and client-side caching. +.. function:: cache_control(**kwargs) + + This decorator patches the response's ``Cache-Control`` header by adding + all of the keyword arguments to it. See + :func:`~django.utils.cache.patch_cache_control` for the details of the + transformation. + .. function:: never_cache(view_func) This decorator adds a ``Cache-Control: max-age=0, no-cache, no-store,