Merge pull request #726 from ijackson/treebuild-docs

Improve docs and xrefs re tree building

Author: ehuss

src/build.rs

@@ -64,7 +64,15 @@ pub struct RepoBuilder<'cb> {
 pub type RemoteCreate<'cb> =
     dyn for<'a> FnMut(&'a Repository, &str, &str) -> Result<Remote<'a>, Error> + 'cb;
 
-/// A builder struct for git tree updates, for use with `git_tree_create_updated`.
+/// A builder struct for git tree updates.
+///
+/// Paths passed to `remove` and `upsert` can be multi-component paths, i.e. they
+/// may contain slashes.
+///
+/// This is a higher-level tree update facility.  There is also [`TreeBuilder`]
+/// which is lower-level (and operates only on one level of the tree at a time).
+///
+/// [`TreeBuilder`]: crate::TreeBuilder
 pub struct TreeUpdateBuilder {
     updates: Vec<raw::git_tree_update>,
     paths: Vec<CString>,

src/treebuilder.rs

@@ -6,7 +6,15 @@ use libc::{c_int, c_void};
 use crate::util::{Binding, IntoCString};
 use crate::{panic, raw, tree, Error, Oid, Repository, TreeEntry};
 
-/// Constructor for in-memory trees
+/// Constructor for in-memory trees (low-level)
+///
+/// You probably want to use [`build::TreeUpdateBuilder`] instead.
+///
+/// This is the more raw of the two tree update facilities.  It
+/// handles only one level of a nested tree structure at a time.  Each
+/// path passed to `insert` etc. must be a single component.
+///
+/// [`build::TreeUpdateBuilder`]: crate::build::TreeUpdateBuilder
 pub struct TreeBuilder<'repo> {
     raw: *mut raw::git_treebuilder,
     _marker: marker::PhantomData<&'repo Repository>,