document new methods (and rename Batching to NewBatch for consistency).

batch.go

@@ -4,7 +4,10 @@ import (
 	cid "github.com/ipfs/go-cid"
 )
 
-func Batching(ds DAGService) *Batch {
+// NewBatch returns a node buffer (Batch) that buffers nodes internally and
+// commits them to the underlying DAGService in batches. Use this if you intend
+// to add a lot of nodes all at once.
+func NewBatch(ds DAGService) *Batch {
 	return &Batch{
 		ds:      ds,
 		MaxSize: 8 << 20,
@@ -26,6 +29,8 @@ type Batch struct {
 	MaxBlocks int
 }
 
+// Add a node to this batch of nodes, potentially committing the set of batched
+// nodes to the underlying DAGService.
 func (t *Batch) Add(nd Node) (*cid.Cid, error) {
 	t.nodes = append(t.nodes, nd)
 	t.size += len(nd.RawData())
@@ -35,6 +40,9 @@ func (t *Batch) Add(nd Node) (*cid.Cid, error) {
 	return nd.Cid(), nil
 }
 
+// Commit commits the buffered of nodes to the underlying DAGService.
+// Make sure to call this after you're done adding nodes to the batch to ensure
+// that they're actually added to the DAGService.
 func (t *Batch) Commit() error {
 	_, err := t.ds.AddMany(t.nodes)
 	t.nodes = nil

daghelpers.go

@@ -7,8 +7,8 @@ import (
 )
 
 // GetDAG will fill out all of the links of the given Node.
-// It returns a channel of nodes, which the caller can receive
-// all the child nodes of 'root' on, in proper order.
+// It returns an array of NodePromise with the linked nodes all in the proper
+// order.
 func GetDAG(ctx context.Context, ds DAGService, root Node) []*NodePromise {
 	var cids []*cid.Cid
 	for _, lnk := range root.Links() {

merkledag.go

@@ -17,9 +17,15 @@ type NodeOption struct {
 
 // The basic Node resolution service.
 type NodeGetter interface {
+	// Get retrieves nodes by CID. Depending on the NodeGetter
+	// implementation, this may involve fetching the Node from a remote
+	// machine; consider setting a deadline in the context.
 	Get(context.Context, *cid.Cid) (Node, error)
 
 	// TODO(ipfs/go-ipfs#4009): Remove this method after fixing.
+
+	// OfflineNodeGetter returns an version of this NodeGetter that will
+	// make no network requests.
 	OfflineNodeGetter() NodeGetter
 }
 
@@ -27,10 +33,17 @@ type NodeGetter interface {
 // objects faster.
 type LinkGetter interface {
 	NodeGetter
+
 	// TODO(ipfs/go-ipld-format#9): This should return []*cid.Cid
+
+	// GetLinks returns the children of the node refered to by the given
+	// CID.
 	GetLinks(ctx context.Context, nd *cid.Cid) ([]*Link, error)
 }
 
+// GetLinks returns the CIDs of the children of the given node. Prefer this
+// method over looking up the node itself and calling `Links()` on it as this
+// method may be able to use a link cache.
 func GetLinks(ctx context.Context, ng NodeGetter, c *cid.Cid) ([]*Link, error) {
 	if c.Type() == cid.Raw {
 		return nil, nil
@@ -49,16 +62,22 @@ func GetLinks(ctx context.Context, ng NodeGetter, c *cid.Cid) ([]*Link, error) {
 type DAGService interface {
 	NodeGetter
 
+	// Add adds a node to this DAG.
 	Add(Node) (*cid.Cid, error)
 
+	// Remove removes a node from this DAG.
+	//
+	// If the node is not in this DAG, Remove returns ErrNotFound.
 	// TODO(ipfs/go-ipfs#4010): Change this to take a CID.
 	// This will require a fair amount of refactoring.
 	Remove(Node) error
 
-	// TODO: Consider using []NodePromise and providing helper functions
-	// that take []NodePromise and return channels that yield nodes both
-	// in-order and as-ready.
+	// GetMany returns a channel of NodeOptions given a set of CIDs.
 	GetMany(context.Context, []*cid.Cid) <-chan *NodeOption
 
+	// AddMany adds many nodes to this DAG.
+	//
+	// Consider using NewBatch instead of calling this directly if you need
+	// to add an unbounded number of nodes to avoid buffering too much.
 	AddMany([]Node) ([]*cid.Cid, error)
 }