Rev 4559: Add some better docs to write_inventory to clarify performance, etc. in http://bazaar.launchpad.net/~jameinel/bzr/1.18-bundle-and-stack-393349

[John Arbash Meinel]

At http://bazaar.launchpad.net/~jameinel/bzr/1.18-bundle-and-stack-393349

------------------------------------------------------------
revno: 4559
revision-id: john at arbash-meinel.com-20090729174434-lhvpun86ynnoul47
parent: john at arbash-meinel.com-20090727180319-of88nkq0bwjzr9hk
committer: John Arbash Meinel <john at arbash-meinel.com>
branch nick: 1.18-bundle-and-stack-393349
timestamp: Wed 2009-07-29 12:44:34 -0500
message:
  Add some better docs to write_inventory to clarify performance, etc.
-------------- 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):