Rev 2468: Document the user of TreeBuilder somewhat. in file:///home/robertc/source/baz/build-branch/

[Robert Collins]

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

------------------------------------------------------------
revno: 2468
revision-id: robertc at robertcollins.net-20070427003620-6fjf8dbiblgt5am7
parent: robertc at robertcollins.net-20070427001815-3m1u2fk695um4oyb
committer: Robert Collins <robertc at robertcollins.net>
branch nick: build-branch
timestamp: Fri 2007-04-27 10:36:20 +1000
message:
  Document the user of TreeBuilder somewhat.
modified:
  HACKING                        HACKING-20050805200004-2a5dc975d870f78c
=== modified file 'HACKING'
--- a/HACKING	2007-04-24 14:19:24 +0000
+++ b/HACKING	2007-04-27 00:36:20 +0000
@@ -14,7 +14,7 @@
   test before writing the code.
 
   In general, you can test at either the command-line level or the
-  internal API level.  See Writing Tests below for more detail.
+  internal API level.  See Writing tests below for more detail.
 
 * Try to practice Test-Driven Development.  before fixing a bug, write a
   test case so that it does not regress.  Similarly for adding a new
@@ -421,6 +421,29 @@
     process will not load plugins unless ``--allow-plugins`` is supplied.
 
 
+Test support
+------------
+
+We have a rich collection of tools to support writing tests. Please use
+them in preference to ad-hoc solutions as they provide portability and
+performance benefits.
+
+TreeBuilder
+~~~~~~~~~~~
+
+The ``TreeBuilder`` interface allows the construction of arbitrary trees
+with a declarative interface. A sample session might look like::
+
+  tree = self.make_branch_and_tree('path')
+  builder = TreeBuilder()
+  builder.start_tree(tree)
+  builder.build(['foo', "bar/", "bar/file"])
+  tree.commit('commit the tree')
+  builder.finish_tree()
+
+Please see bzrlib.treebuilder for more details.
+
+
 Doctests
 --------