more README

Change-Id: I569e7fd3cf9e418af03285f4f499f5ea3a0c0dc0

1 files changed, 38 insertions, 0 deletions

diff --git a/svl/README b/svl/README
index 2ab2f1d82794..c2cca3f58a2e 100644
--- a/svl/README
+++ b/svl/README
@@ -10,3 +10,41 @@ formats, to Chart regression line properties.
 
 There are lots of other useful helpers in here for various office
 tasks; much of this code was originally moved from svx/sfx2.
+
+== Items, Pools and Sets ==
+
+=== SfxPoolItem ===
+
+A small reference counted piece of data.  Many subclasses, each with a
+unique integer to identify its type (WhichId).  Can be compared for equality
+(operator==), Clone()d, and converted to/from uno::Any (QueryValue/PutValue).
+
+A pool item may have value semantics (SFX_ITEM_POOLABLE), meaning that
+there will generally be only one instance that compares equal per item pool,
+or not, in which case the item will be Clone()d quite a bit.
+
+=== SfxItemPool ===
+
+Usually there is one item pool per document, with a range of valid WhichIds
+that is specific to the type of document.
+
+The item pool owns all instances of SfxPoolItem or its subclasses that have
+ever been added to an item set.  It also contains a default item for
+every WhichId, which will be (depending on parameters) returned from item
+sets if the set does not contain an item at this WhichId.
+
+=== SfxItemSet ===
+
+The item set can be created with a user-supplied range of WhichIds; it
+will accept SfxPoolItems with matching WhichIds and ignore attempts to
+insert items with non-matching WhichIds.
+
+Items that are succesfully inserted into the set will be stored in the
+set's SfxItemPool, and for poolable items only a single instance that
+compares equal under the predicate operator== will be stored in the pool,
+regardless of how many sets contain it, thus conserving memory.
+
+There are members _pWhichRanges for the valid ranges (as pairs of WhichIds),
+_nCount for the number of items contained, and _aItems for the pointers to
+the actual items.
+