Update documentation.

1 files changed, 30 insertions, 19 deletions

diff --git a/README.rst b/README.rst
index 073a62b..4b01431 100644
--- a/README.rst
+++ b/README.rst
@@ -1,9 +1,9 @@
 cachetools
 ========================================================================
 
-This module provides various memoizing collections and function
-decorators, including a variant of the Python 3 Standard Library
-`functools.lru_cache`_ decorator.
+This module provides various memoizing collections and decorators,
+including a variant of the Python 3 Standard Library
+`functools.lru_cache` function decorator.
 
 .. code-block:: pycon
 
@@ -12,26 +12,36 @@ decorators, including a variant of the Python 3 Standard Library
    >>> cache['first'] = 1
    >>> cache['second'] = 2
    >>> cache
-   LRUCache(OrderedDict([('first', 1), ('second', 2)]), maxsize=2)
+   LRUCache(OrderedDict([('first', 1), ('second', 2)]), size=2, maxsize=2)
    >>> cache['third'] = 3
    >>> cache
-   LRUCache(OrderedDict([('second', 2), ('third', 3)]), maxsize=2)
+   LRUCache(OrderedDict([('second', 2), ('third', 3)]), size=2, maxsize=2)
    >>> cache['second']
    2
    >>> cache
-   LRUCache(OrderedDict([('third', 3), ('second', 2)]), maxsize=2)
+   LRUCache(OrderedDict([('third', 3), ('second', 2)]), size=2, maxsize=2)
    >>> cache['fourth'] = 4
    >>> cache
-   LRUCache(OrderedDict([('second', 2), ('fourth', 4)]), maxsize=2)
+   LRUCache(OrderedDict([('second', 2), ('fourth', 4)]), size=2, maxsize=2)
 
-For the purpose of this module, a *cache* is a mutable mapping_ of
-fixed size, defined by its ``maxsize`` attribute.  When the cache is
-full, i.e. ``len(cache) == cache.maxsize``, the cache must choose
-which item(s) to discard based on a suitable `cache algorithm`_.
+For the purpose of this module, a *cache* is a mutable_ mapping_ with
+additional attributes ``size`` and ``maxsize``, which hold the current
+and maximum size of the cache, and a (possibly static) method
+``getsizeof``.
+
+The current size of the cache is the sum of the results of
+``getsizeof`` applied to each of the cache's values, i.e. ``cache.size
+== sum(map(cache.getsizeof, cache.values()), 0)``.  As a special case,
+if ``getsizeof`` returns ``1`` irrespective of its argument,
+``cache.size == len(cache)``.
+
+When the cache is full, i.e. ``cache.size > cache.maxsize``, the cache
+must choose which item(s) to discard based on a suitable `cache
+algorithm`_.
 
 This module provides various cache implementations based on different
 cache algorithms, as well as decorators for easily memoizing function
-calls, and utilities for creating custom cache implementations.
+and method calls.
 
 
 Installation
@@ -45,19 +55,19 @@ Install cachetools using pip::
 Project Resources
 ------------------------------------------------------------------------
 
-- `Documentation`_
-- `Issue Tracker`_
-- `Source Code`_
-- `Change Log`_
-
-.. image:: https://pypip.in/v/cachetools/badge.png
+.. image:: http://img.shields.io/pypi/v/cachetools.svg
     :target: https://pypi.python.org/pypi/cachetools/
     :alt: Latest PyPI version
 
-.. image:: https://pypip.in/d/cachetools/badge.png
+.. image:: http://img.shields.io/pypi/dm/cachetools.svg
     :target: https://pypi.python.org/pypi/cachetools/
     :alt: Number of PyPI downloads
 
+- `Documentation`_
+- `Issue Tracker`_
+- `Source Code`_
+- `Change Log`_
+
 
 License
 ------------------------------------------------------------------------
@@ -68,6 +78,7 @@ Licensed under the `MIT License`_.
 
 
 .. _functools.lru_cache: http://docs.python.org/3.4/library/functools.html#functools.lru_cache
+.. _mutable: http://docs.python.org/dev/glossary.html#term-mutable
 .. _mapping: http://docs.python.org/dev/glossary.html#term-mapping
 .. _cache algorithm: http://en.wikipedia.org/wiki/Cache_algorithms