Rev 2473: Document basic usage. in file:///home/robertc/source/baz/build-branch/

[Robert Collins]

At file:///home/robertc/source/baz/build-branch/

------------------------------------------------------------
revno: 2473
revision-id: robertc at robertcollins.net-20070427031300-wqxk6eo04pxn6trg
parent: robertc at robertcollins.net-20070427030205-ll4s3d57mf0dcaqk
committer: Robert Collins <robertc at robertcollins.net>
branch nick: build-branch
timestamp: Fri 2007-04-27 13:13:00 +1000
message:
  Document basic usage.
modified:
  HACKING                        HACKING-20050805200004-2a5dc975d870f78c
  bzrlib/branchbuilder.py        branchbuilder.py-20070427022007-zlxpqz2lannhk6y8-1
=== modified file 'HACKING'
--- a/HACKING	2007-04-27 00:36:20 +0000
+++ b/HACKING	2007-04-27 03:13:00 +0000
@@ -443,6 +443,19 @@
 
 Please see bzrlib.treebuilder for more details.
 
+BranchBuilder
+~~~~~~~~~~~~~
+
+The ``BranchBuilder`` interface allows the creation of test branches in a
+quick and easy manner. A sample session::
+
+  builder = BranchBuilder(self.get_transport().clone('relpath'))
+  builder.build_commit()
+  builder.build_commit()
+  builder.build_commit()
+  branch = builder.get_branch()
+
+Please see bzrlib.branchbuilder for more details.
 
 Doctests
 --------

=== modified file 'bzrlib/branchbuilder.py'
--- a/bzrlib/branchbuilder.py	2007-04-27 03:02:05 +0000
+++ b/bzrlib/branchbuilder.py	2007-04-27 03:13:00 +0000
@@ -20,7 +20,19 @@
 
 
 class BranchBuilder(object):
-    """A BranchBuilder aids creating Branches with particular shapes."""
+    """A BranchBuilder aids creating Branches with particular shapes.
+    
+    The expected way to use BranchBuilder is to construct a
+    BranchBuilder on the transport you want your branch on, and then call
+    appropriate build_ methods on it to get the shape of history you want.
+
+    For instance:
+      builder = BranchBuilder(self.get_transport().clone('relpath'))
+      builder.build_commit()
+      builder.build_commit()
+      builder.build_commit()
+      branch = builder.get_branch()
+    """
 
     def __init__(self, transport):
         """Construct a BranchBuilder on transport.