[Checkins] SVN: z3c.dobbin/trunk/ Updated documentation.

[Malthe Borch]

Log message for revision 87940:
  Updated documentation.

Changed:
  U   z3c.dobbin/trunk/CHANGES.txt
  U   z3c.dobbin/trunk/README.txt
  U   z3c.dobbin/trunk/docs/DEVELOPER.txt

-=-
Modified: z3c.dobbin/trunk/CHANGES.txt
===================================================================
--- z3c.dobbin/trunk/CHANGES.txt	2008-07-02 21:56:01 UTC (rev 87939)
+++ z3c.dobbin/trunk/CHANGES.txt	2008-07-02 21:57:42 UTC (rev 87940)
@@ -1,9 +1,13 @@
 Change log
 ==========
 
-0.3.1 dev
----------
+0.3.1
+-----
 
+- Use native UUID column type (available on PostgreSQL); compatibility
+  with SQLite is preserved due to its weak typing.
+  [malthe]
+
 - Basic type factories are now registered as components.
   [malthe]
 

Modified: z3c.dobbin/trunk/README.txt
===================================================================
--- z3c.dobbin/trunk/README.txt	2008-07-02 21:56:01 UTC (rev 87939)
+++ z3c.dobbin/trunk/README.txt	2008-07-02 21:57:42 UTC (rev 87940)
@@ -5,11 +5,12 @@
 semi-transparent object persistance model.
 
 It relies on descriptive attribute and field declarations based on
-zope.interface and zope.schema.
+zope.interface and zope.schema. Strong typing is supported (and
+encouraged when possible), but not required.
 
-Tables are created automatically with a 1:1 correspondence to an
-interface with no inheritance (minimal interface). As such, objects
-are modelled as a join between the interfaces it implements.
+Tables are created on-the-fly with 1:1 correspondence to interfaces
+with no inheritance (base interface). As such, objects are modelled as
+a join between the interfaces they implement.
 
 Authors
 -------

Modified: z3c.dobbin/trunk/docs/DEVELOPER.txt
===================================================================
--- z3c.dobbin/trunk/docs/DEVELOPER.txt	2008-07-02 21:56:01 UTC (rev 87939)
+++ z3c.dobbin/trunk/docs/DEVELOPER.txt	2008-07-02 21:57:42 UTC (rev 87940)
@@ -1,50 +1,41 @@
 Developer documentation
 =======================
 
-This section details the object persistence model and the relations
-machinery.
+Objects are mapped by their specification. Polymorphic attributes are
+declared as interface attributes; strong typing may be declared using
+schema fields; Attributes that are not declared in a schema or
+interface are considered volatile.
 
-Introduction
-------------
+Unique identifiers (UUID)
+-------------------------
 
-Objects that need persisting are required to declare their attributes
-in an interface. Attributes that are not declared are considered
-volatile.
+A 16-byte unique identification number is used.
 
-Concrete attributes may be strongly typed using the schema fields that
-correspond to their type; polymorphic attributes are available using
-relational properties.
-
 Relations
 ---------
 
-There are two kinds of objects that can be related: instances and
-rocks. Relations are polymorphic such that they support both kinds.
+Polymorphic attributes are always stored using foreign key
+relations. This is handled transparently by the framework.
 
-An attribute can hold a single relation or many, using one of the
-built-in sequence types: list, tuple, set, dict.
+The target of a relation may be a basic type such as a string,
+integer, tuple or list, or it may be a mapped object.
 
-The following fields allow polymorphic relations of any kind:
+The following fields allow polymorphic relations of any kind with the
+type declared on assignment.
 
   * zope.schema.Object
   * zope.interface.Attribute
 
-Additional structure can be declared using the sequence fields:
+Collections are instrumented objects and may be declared using the
+sequence fields:
 
   * zope.schema.List
   * zope.schema.Dict
   * zope.schema.Set
 
-When translated to column in a table, all relations are soup object
-references; the soup specification will reflect the type.
+A note on dictionaries: Dictionaries are keyed by (unicode)
+string. Mapped instances may be used as keys in which case a string
+representation of the unique instance identifier is used. Dictionaries
+support polymorphic values with type set on assignment.
 
-Essentially, all polymorphic relations are many-to-many from a
-database perspective. 
 
-Collections
------------
-
-Dictionaries are keyed by (unicode) string. Soup objects may be used
-as keys in which case a string representation of the UUID is
-used. Dictionaries are polymorphic such that any kind of value may be
-assigned for an entry.