Rev 4562: Merge the docstring update. in http://bazaar.launchpad.net/~jameinel/bzr/1.18-2a-bundle-performance

[John Arbash Meinel]

At http://bazaar.launchpad.net/~jameinel/bzr/1.18-2a-bundle-performance

------------------------------------------------------------
revno: 4562 [merge]
revision-id: john at arbash-meinel.com-20090730203044-4nj22r3fw1y4d4zg
parent: john at arbash-meinel.com-20090728202147-g2oqb05uvkt85jh8
parent: john at arbash-meinel.com-20090729174434-lhvpun86ynnoul47
committer: John Arbash Meinel <john at arbash-meinel.com>
branch nick: 1.18-2a-bundle-performance
timestamp: Thu 2009-07-30 15:30:44 -0500
message:
  Merge the docstring update.
modified:
  bzrlib/serializer.py           serializer.py-20090402143702-wmkh9cfjhwpju0qi-1
-------------- next part --------------
=== modified file 'bzrlib/serializer.py'
--- a/bzrlib/serializer.py	2009-06-15 19:04:38 +0000
+++ b/bzrlib/serializer.py	2009-07-29 17:44:34 +0000
@@ -27,10 +27,26 @@
     squashes_xml_invalid_characters = False
 
     def write_inventory(self, inv, f):
-        """Write inventory to a file"""
+        """Write inventory to a file.
+
+        Note: this is a *whole inventory* operation, and should only be used
+        sparingly, as it does not scale well with large trees.
+        """
         raise NotImplementedError(self.write_inventory)
 
     def write_inventory_to_string(self, inv):
+        """Produce a simple string representation of an inventory.
+
+        Note: this is a *whole inventory* operation, and should only be used
+        sparingly, as it does not scale well with large trees.
+
+        The requirement for the contents of the string is that it can be passed
+        to read_inventory_from_string and the result is an identical inventory
+        in memory.
+
+        (All serializers as of 2009-07-29 produce XML, but this is not mandated
+        by the interface.)
+        """
         raise NotImplementedError(self.write_inventory_to_string)
 
     def read_inventory_from_string(self, string, revision_id=None,
@@ -52,6 +68,7 @@
         raise NotImplementedError(self.read_inventory_from_string)
 
     def read_inventory(self, f, revision_id=None):
+        """See read_inventory_from_string."""
         raise NotImplementedError(self.read_inventory)
 
     def write_revision(self, rev, f):