[kupfer: 48/53] doc: Add caching remark to ``decorate_item``

[Ulrik Sverdrup <usverdrup src gnome org>]

commit 2d35bb92169f3225a449cb51d2905643326b4127
Author: Ulrik Sverdrup <ulrik sverdrup gmail com>
Date:   Thu Mar 24 17:22:41 2011 +0100

    doc: Add caching remark to ``decorate_item``

 Documentation/PluginAPI.rst |    5 +++++
 1 files changed, 5 insertions(+), 0 deletions(-)
---
diff --git a/Documentation/PluginAPI.rst b/Documentation/PluginAPI.rst
index 2ffc5a0..8af077c 100644
--- a/Documentation/PluginAPI.rst
+++ b/Documentation/PluginAPI.rst
@@ -584,6 +584,11 @@ Otherwise content-only sources are listed in ``__kupfer_contents__``.
     Return an instance of a Source (normally of the same type as the
     content decorator itself) that is the content for the object
     ``leaf``.  Return ``None`` if not applicable.
+
+    Sources returned from ``decorate_item`` go into the common Source
+    pool. The new source instance will not be used if the returned
+    instance is equivalent (as defined by class and ``reepr_key``
+    above).
     
 
 Source Attributes