[Zope3-checkins] CVS: Zope3/src/zope/app/interfaces - annotation.py:1.4

[Jim Fulton]

Update of /cvs-repository/Zope3/src/zope/app/interfaces
In directory cvs.zope.org:/tmp/cvs-serv18678

Modified Files:
	annotation.py 
Log Message:
Improved doc strings.


=== Zope3/src/zope/app/interfaces/annotation.py 1.3 => 1.4 ===
--- Zope3/src/zope/app/interfaces/annotation.py:1.3	Mon Dec 30 16:14:25 2002
+++ Zope3/src/zope/app/interfaces/annotation.py	Thu Mar 13 15:39:14 2003
@@ -32,7 +32,19 @@
     """
 
 class IAnnotations(IAnnotatable):
-    """Stores arbitrary application data under package-unique keys."""
+    """Stores arbitrary application data under package-unique keys.
+
+    By "package-unique keys", we mean keys that are are unique by
+    virtua of including the dotted name of a package as a prefex.  A
+    package name is used to limit the authority for picking names for
+    a package to the people using that package.
+
+    For example, when implementing annotations for storing Zope
+    Dublin-Core meta-data, we use the key::
+
+      "zope.app.dublincore.ZopeDublinCore"
+
+    """
 
     def __getitem__(key):
         """Return the annotation stored under key.
@@ -41,7 +53,8 @@
         """
 
     def get(key, default=None):
-        """Return the annotation stored under key, or default if not found."""
+        """Return the annotation stored under key, or default if not found.
+        """
 
     def __setitem__(key, memento):
         """Store annotation under key.
@@ -57,7 +70,9 @@
         """
 
 class IAttributeAnnotatable(IAnnotatable):
-    """
-    Marker interface giving permission for an IAnnotations adapter to store
-    data in an attribute named __annotations__.
+    """Marker indicating that annotations can be stored on an attribute
+    
+    This is a marker interface giving permission for an IAnnotations
+    adapter to store data in an attribute named __annotations__.
+
     """