doc: improve object iterators godoc.

6 files changed, 38 insertions, 27 deletions

diff --git a/plumbing/object/blob.go b/plumbing/object/blob.go
index 76b0e7d..e44753c 100644
--- a/plumbing/object/blob.go
+++ b/plumbing/object/blob.go
@@ -92,16 +92,17 @@ type BlobIter struct {
 	s storer.EncodedObjectStorer
 }
 
-// NewBlobIter returns a BlobIter for the given repository and underlying
-// object iterator.
+// NewBlobIter takes a storer.EncodedObjectStorer and a
+// storer.EncodedObjectIter and returns a *BlobIter that iterates over all
+// blobs contained in the storer.EncodedObjectIter.
 //
-// The returned BlobIter will automatically skip over non-blob objects.
+// Any non-blob object returned by the storer.EncodedObjectIter is skipped.
 func NewBlobIter(s storer.EncodedObjectStorer, iter storer.EncodedObjectIter) *BlobIter {
 	return &BlobIter{iter, s}
 }
 
-// Next moves the iterator to the next blob and returns a pointer to it. If it
-// has reached the end of the set it will return io.EOF.
+// Next moves the iterator to the next blob and returns a pointer to it. If
+// there are no more blobs, it returns io.EOF.
 func (iter *BlobIter) Next() (*Blob, error) {
 	for {
 		obj, err := iter.EncodedObjectIter.Next()
diff --git a/plumbing/object/commit.go b/plumbing/object/commit.go
index 394f04f..9bb1d3c 100644
--- a/plumbing/object/commit.go
+++ b/plumbing/object/commit.go
@@ -53,12 +53,12 @@ func DecodeCommit(s storer.EncodedObjectStorer, o plumbing.EncodedObject) (*Comm
 	return c, nil
 }
 
-// Tree returns the Tree from the commit
+// Tree returns the Tree from the commit.
 func (c *Commit) Tree() (*Tree, error) {
 	return GetTree(c.s, c.tree)
 }
 
-// Parents return a CommitIter to the parent Commits
+// Parents return a CommitIter to the parent Commits.
 func (c *Commit) Parents() *CommitIter {
 	return NewCommitIter(c.s,
 		storer.NewEncodedObjectLookupIter(c.s, plumbing.CommitObject, c.parents),
@@ -158,7 +158,8 @@ func (c *Commit) Decode(o plumbing.EncodedObject) (err error) {
 	}
 }
 
-// History return a slice with the previous commits in the history of this commit
+// History returns a slice with the previous commits in the history of this
+// commit, sorted in reverse chronological order.
 func (c *Commit) History() ([]*Commit, error) {
 	var commits []*Commit
 	err := WalkCommitHistory(c, func(commit *Commit) error {
@@ -231,16 +232,17 @@ type CommitIter struct {
 	s storer.EncodedObjectStorer
 }
 
-// NewCommitIter returns a CommitIter for the given object storer and underlying
-// object iterator.
+// NewCommitIter takes a storer.EncodedObjectStorer and a
+// storer.EncodedObjectIter and returns a *CommitIter that iterates over all
+// commits contained in the storer.EncodedObjectIter.
 //
-// The returned CommitIter will automatically skip over non-commit objects.
+// Any non-commit object returned by the storer.EncodedObjectIter is skipped.
 func NewCommitIter(s storer.EncodedObjectStorer, iter storer.EncodedObjectIter) *CommitIter {
 	return &CommitIter{iter, s}
 }
 
-// Next moves the iterator to the next commit and returns a pointer to it. If it
-// has reached the end of the set it will return io.EOF.
+// Next moves the iterator to the next commit and returns a pointer to it. If
+// there are no more commits, it returns io.EOF.
 func (iter *CommitIter) Next() (*Commit, error) {
 	obj, err := iter.EncodedObjectIter.Next()
 	if err != nil {
diff --git a/plumbing/object/file.go b/plumbing/object/file.go
index 618cea7..4caed6b 100644
--- a/plumbing/object/file.go
+++ b/plumbing/object/file.go
@@ -56,15 +56,20 @@ func (f *File) Lines() ([]string, error) {
 	return splits, nil
 }
 
+// FileIter provides an iterator for the files in a tree.
 type FileIter struct {
 	s storer.EncodedObjectStorer
 	w TreeWalker
 }
 
+// NewFileIter takes a storer.EncodedObjectStorer and a Tree and returns a
+// *FileIter that iterates over all files contained in the tree, recursively.
 func NewFileIter(s storer.EncodedObjectStorer, t *Tree) *FileIter {
 	return &FileIter{s: s, w: *NewTreeWalker(t, true)}
 }
 
+// Next moves the iterator to the next file and returns a pointer to it. If
+// there are no more files, it returns io.EOF.
 func (iter *FileIter) Next() (*File, error) {
 	for {
 		name, entry, err := iter.w.Next()
diff --git a/plumbing/object/object.go b/plumbing/object/object.go
index 5512932..53c7e6c 100644
--- a/plumbing/object/object.go
+++ b/plumbing/object/object.go
@@ -158,14 +158,15 @@ type ObjectIter struct {
 	s storer.EncodedObjectStorer
 }
 
-// NewObjectIter returns a ObjectIter for the given repository and underlying
-// object iterator.
+// NewObjectIter takes a storer.EncodedObjectStorer and a
+// storer.EncodedObjectIter and returns an *ObjectIter that iterates over all
+// objects contained in the storer.EncodedObjectIter.
 func NewObjectIter(s storer.EncodedObjectStorer, iter storer.EncodedObjectIter) *ObjectIter {
 	return &ObjectIter{iter, s}
 }
 
-// Next moves the iterator to the next object and returns a pointer to it. If it
-// has reached the end of the set it will return io.EOF.
+// Next moves the iterator to the next object and returns a pointer to it. If
+// there are no more objects, it returns io.EOF.
 func (iter *ObjectIter) Next() (Object, error) {
 	for {
 		obj, err := iter.EncodedObjectIter.Next()
diff --git a/plumbing/object/tag.go b/plumbing/object/tag.go
index 1b18dbf..7792491 100644
--- a/plumbing/object/tag.go
+++ b/plumbing/object/tag.go
@@ -223,16 +223,17 @@ type TagIter struct {
 	s storer.EncodedObjectStorer
 }
 
-// NewTagIter returns a TagIter for the given object storer and underlying
-// object iterator.
+// NewTagIter takes a storer.EncodedObjectStorer and a
+// storer.EncodedObjectIter and returns a *TagIter that iterates over all
+// tags contained in the storer.EncodedObjectIter.
 //
-// The returned TagIter will automatically skip over non-tag objects.
+// Any non-tag object returned by the storer.EncodedObjectIter is skipped.
 func NewTagIter(s storer.EncodedObjectStorer, iter storer.EncodedObjectIter) *TagIter {
 	return &TagIter{iter, s}
 }
 
-// Next moves the iterator to the next tag and returns a pointer to it. If it
-// has reached the end of the set it will return io.EOF.
+// Next moves the iterator to the next tag and returns a pointer to it. If
+// there are no more tags, it returns io.EOF.
 func (iter *TagIter) Next() (*Tag, error) {
 	obj, err := iter.EncodedObjectIter.Next()
 	if err != nil {
diff --git a/plumbing/object/tree.go b/plumbing/object/tree.go
index 546dd74..3bcd80a 100644
--- a/plumbing/object/tree.go
+++ b/plumbing/object/tree.go
@@ -431,16 +431,17 @@ type TreeIter struct {
 	s storer.EncodedObjectStorer
 }
 
-// NewTreeIter returns a TreeIter for the given repository and underlying
-// object iterator.
+// NewTreeIter takes a storer.EncodedObjectStorer and a
+// storer.EncodedObjectIter and returns a *TreeIter that iterates over all
+// tree contained in the storer.EncodedObjectIter.
 //
-// The returned TreeIter will automatically skip over non-tree objects.
+// Any non-tree object returned by the storer.EncodedObjectIter is skipped.
 func NewTreeIter(s storer.EncodedObjectStorer, iter storer.EncodedObjectIter) *TreeIter {
 	return &TreeIter{iter, s}
 }
 
-// Next moves the iterator to the next tree and returns a pointer to it. If it
-// has reached the end of the set it will return io.EOF.
+// Next moves the iterator to the next tree and returns a pointer to it. If
+// there are no more trees, it returns io.EOF.
 func (iter *TreeIter) Next() (*Tree, error) {
 	for {
 		obj, err := iter.EncodedObjectIter.Next()