warn about validation vs invalidation and cleanup feature list

README.md

@@ -9,16 +9,18 @@ Introduction
 
 This bundle offers tools to improve HTTP caching with Symfony2. It provides
 global configuration options to set caching headers based on the path,
-controller and other aspects of the request. It provides services for the
-FOSHttpCache library tools to actively invalidate caching proxies and some
-additional tools that can help when working with a caching proxy.
+controller and other aspects of the request. In addition, it provides services
+for the FOSHttpCache library tools to actively invalidate caching proxies and
+some additional tools that can help when working with a caching proxy.
 
 Features
 --------
 
-* Set path-based cache expiration headers via your app configuration.
-* Set up an invalidation scheme without writing PHP code.
-* Send invalidation requests with minimal impact on performance.
+* Set path-based cache expiration headers via your app configuration;
+* Set up an invalidation scheme without writing PHP code;
+* Tag your responses and invalidate cache based on tags;
+* Send invalidation requests with minimal impact on performance;
+* Differentiate caches based on user *type* (e.g. roles);
 * Easily implement your own HTTP cache client.
 
 Documentation

Resources/doc/features/invalidation.rst

@@ -14,6 +14,14 @@ fetch a fresh copy from the backend application and serve that instead. By
     So for the following examples to work you must first
     :ref:`configure your proxy <foshttpcache:proxy-configuration>`.
 
+.. tip::
+
+    Invalidation can result in better performance compared to the validation
+    caching model, but is more complex. Read the
+    :ref:`Introduction to Cache Invalidation <foshttpcache:invalidation introduction>`
+    of the FOSHttpCache documentation to learn about the differences and decide
+    which model is right for you.
+
 Cache Manager
 -------------
 

Resources/doc/index.rst

@@ -4,11 +4,12 @@ FOSHttpCacheBundle
 This is the documentation for the `FOSHttpCacheBundle <https://github.com/FriendsOfSymfony/FOSHttpCacheBundle>`_.
 Use the FOSHttpCacheBundle to:
 
-* set HTTP caching headers in your application configuration based on request
-  properties such as path and controller;
-* tag your response caches with annotations;
-* invalidate cached paths, routes and tags with the FOSHttpCache_ library;
-* differentiate cached content per user type.
+* Set path-based cache expiration headers via your app configuration;
+* Set up an invalidation scheme without writing PHP code;
+* Tag your responses and invalidate cache based on tags;
+* Send invalidation requests with minimal impact on performance with the FOSHttpCache_ library;
+* Differentiate caches based on user *type* (e.g. roles);
+* Easily implement your own HTTP cache client.
 
 Contents
 --------