From 2b1efd219e1f20d9a0bc380a26074c9d8de2ae1f Mon Sep 17 00:00:00 2001
From: "Santiago M. Mola" <santi@mola.io>
Date: Mon, 6 Feb 2017 18:11:10 +0100
Subject: doc: improve docs for object package.

* add package description.

* add godoc to DecodeBlob.

* clarify godoc for Object and Blob.
---
 plumbing/object/blob.go   | 3 ++-
 plumbing/object/object.go | 7 +++++--
 2 files changed, 7 insertions(+), 3 deletions(-)

(limited to 'plumbing/object')

diff --git a/plumbing/object/blob.go b/plumbing/object/blob.go
index f274e70..76b0e7d 100644
--- a/plumbing/object/blob.go
+++ b/plumbing/object/blob.go
@@ -8,7 +8,7 @@ import (
 	"srcd.works/go-git.v4/utils/ioutil"
 )
 
-// Blob is used to store file data - it is generally a file.
+// Blob is used to store arbitrary data - it is generally a file.
 type Blob struct {
 	Hash plumbing.Hash
 	Size int64
@@ -26,6 +26,7 @@ func GetBlob(s storer.EncodedObjectStorer, h plumbing.Hash) (*Blob, error) {
 	return DecodeBlob(o)
 }
 
+// DecodeObject decodes an encoded object into a *Blob.
 func DecodeBlob(o plumbing.EncodedObject) (*Blob, error) {
 	b := &Blob{}
 	if err := b.Decode(o); err != nil {
diff --git a/plumbing/object/object.go b/plumbing/object/object.go
index 51d9bc4..5512932 100644
--- a/plumbing/object/object.go
+++ b/plumbing/object/object.go
@@ -1,3 +1,5 @@
+// Package object contains implementations of all Git objects and utility
+// functions to work with them.
 package object
 
 import (
@@ -35,8 +37,9 @@ var ErrUnsupportedObject = errors.New("unsupported object type")
 //   	}
 //   }
 //
-// This interface is intentionally different from plumbing.EncodedObject, which is a lower
-// level interface used by storage implementations to read and write objects.
+// This interface is intentionally different from plumbing.EncodedObject, which
+// is a lower level interface used by storage implementations to read and write
+// objects in its encoded form.
 type Object interface {
 	ID() plumbing.Hash
 	Type() plumbing.ObjectType
-- 
cgit 


From 1f39465975d56bbb02f5cdfb1e3e77f41c613f1d Mon Sep 17 00:00:00 2001
From: "Santiago M. Mola" <santi@mola.io>
Date: Tue, 7 Feb 2017 10:02:20 +0100
Subject: doc: improve object iterators godoc.

---
 plumbing/object/blob.go   | 11 ++++++-----
 plumbing/object/commit.go | 18 ++++++++++--------
 plumbing/object/file.go   |  5 +++++
 plumbing/object/object.go |  9 +++++----
 plumbing/object/tag.go    | 11 ++++++-----
 plumbing/object/tree.go   | 11 ++++++-----
 6 files changed, 38 insertions(+), 27 deletions(-)

(limited to 'plumbing/object')

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()
-- 
cgit 


From 62666856d9f4b3150671eb1f215a7072c02c0bc6 Mon Sep 17 00:00:00 2001
From: "Santiago M. Mola" <santi@mola.io>
Date: Tue, 7 Feb 2017 17:26:13 +0100
Subject: doc: add object fields godoc

---
 plumbing/object/blob.go   |  2 ++
 plumbing/object/commit.go | 11 ++++++++---
 plumbing/object/file.go   |  4 ++++
 plumbing/object/tag.go    | 10 +++++++---
 4 files changed, 21 insertions(+), 6 deletions(-)

(limited to 'plumbing/object')

diff --git a/plumbing/object/blob.go b/plumbing/object/blob.go
index e44753c..4c9e84d 100644
--- a/plumbing/object/blob.go
+++ b/plumbing/object/blob.go
@@ -10,7 +10,9 @@ import (
 
 // Blob is used to store arbitrary data - it is generally a file.
 type Blob struct {
+	// Hash of the blob.
 	Hash plumbing.Hash
+	// Size of the (uncompressed) blob.
 	Size int64
 
 	obj plumbing.EncodedObject
diff --git a/plumbing/object/commit.go b/plumbing/object/commit.go
index 9bb1d3c..7238f5c 100644
--- a/plumbing/object/commit.go
+++ b/plumbing/object/commit.go
@@ -22,10 +22,15 @@ type Hash plumbing.Hash
 // commit, a pointer to the previous commit(s), etc.
 // http://schacon.github.io/gitbook/1_the_git_object_model.html
 type Commit struct {
-	Hash      plumbing.Hash
-	Author    Signature
+	// Hash of the commit object.
+	Hash plumbing.Hash
+	// Author is the original author of the commit.
+	Author Signature
+	// Committer is the one performing the commit, might be different from
+	// Author.
 	Committer Signature
-	Message   string
+	// Message is the commit message, contains arbitrary text.
+	Message string
 
 	tree    plumbing.Hash
 	parents []plumbing.Hash
diff --git a/plumbing/object/file.go b/plumbing/object/file.go
index 4caed6b..35e7f24 100644
--- a/plumbing/object/file.go
+++ b/plumbing/object/file.go
@@ -12,8 +12,12 @@ import (
 
 // File represents git file objects.
 type File struct {
+	// Name is the path of the file. It might be relative to a tree,
+	// depending of the function that generates it.
 	Name string
+	// Mode is the file mode.
 	Mode os.FileMode
+	// Blob with the contents of the file.
 	Blob
 }
 
diff --git a/plumbing/object/tag.go b/plumbing/object/tag.go
index 7792491..085e3f6 100644
--- a/plumbing/object/tag.go
+++ b/plumbing/object/tag.go
@@ -20,9 +20,13 @@ import (
 //
 // https://git-scm.com/book/en/v2/Git-Internals-Git-References#Tags
 type Tag struct {
-	Hash       plumbing.Hash
-	Name       string
-	Tagger     Signature
+	// Hash of the tag.
+	Hash plumbing.Hash
+	// Name of the tag.
+	Name string
+	// Tagger is the one who created the tag.
+	Tagger Signature
+	// Message is an arbitrary text message
 	Message    string
 	TargetType plumbing.ObjectType
 	Target     plumbing.Hash
-- 
cgit 


From 77a8f2bfbd2b19d6e19edeb7a9276bc9fe576c00 Mon Sep 17 00:00:00 2001
From: "Santiago M. Mola" <santi@mola.io>
Date: Tue, 7 Feb 2017 17:45:27 +0100
Subject: doc: improve godoc for WalkCommitHistory.

---
 plumbing/object/commit_walker.go | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

(limited to 'plumbing/object')

diff --git a/plumbing/object/commit_walker.go b/plumbing/object/commit_walker.go
index 1514cb3..8d70abe 100644
--- a/plumbing/object/commit_walker.go
+++ b/plumbing/object/commit_walker.go
@@ -13,7 +13,11 @@ type commitWalker struct {
 	cb    func(*Commit) error
 }
 
-// WalkCommitHistory walks the commit history
+// WalkCommitHistory walks the commit history, starting at the given commit and
+// visiting its parents in pre-order. The given callback will be called for each
+// visited commit. Each commit will be visited only once. If the callback returns
+// an error, walking will stop and will return the error. Other errors might be
+// returned if the history cannot be traversed (e.g. missing objects).
 func WalkCommitHistory(c *Commit, cb func(*Commit) error) error {
 	w := &commitWalker{
 		seen:  make(map[plumbing.Hash]bool),
-- 
cgit 


From f3554ac62e29fd3e06c6e1fdeda914ac19cb68fa Mon Sep 17 00:00:00 2001
From: "Santiago M. Mola" <santi@mola.io>
Date: Tue, 7 Feb 2017 17:46:53 +0100
Subject: doc: add godoc to Signature

---
 plumbing/object/object.go | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

(limited to 'plumbing/object')

diff --git a/plumbing/object/object.go b/plumbing/object/object.go
index 53c7e6c..ca5c541 100644
--- a/plumbing/object/object.go
+++ b/plumbing/object/object.go
@@ -77,11 +77,14 @@ func DecodeObject(s storer.EncodedObjectStorer, o plumbing.EncodedObject) (Objec
 // DateFormat is the format being used in the original git implementation
 const DateFormat = "Mon Jan 02 15:04:05 2006 -0700"
 
-// Signature represents an action signed by a person
+// Signature is used to identify who and when created a commit or tag.
 type Signature struct {
-	Name  string
+	// Name represents a person name. It is an arbitrary string.
+	Name string
+	// Email is an email, but it cannot be assumed to be well-formed.
 	Email string
-	When  time.Time
+	// When is the timestamp of the signature.
+	When time.Time
 }
 
 // Decode decodes a byte slice into a signature
-- 
cgit 


From 84b6bd8c22c8683479881a67db03dfdeeeb299ce Mon Sep 17 00:00:00 2001
From: "Santiago M. Mola" <santi@mola.io>
Date: Wed, 8 Feb 2017 10:30:56 +0100
Subject: doc: improve object.Tag godoc.

---
 plumbing/object/tag.go | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

(limited to 'plumbing/object')

diff --git a/plumbing/object/tag.go b/plumbing/object/tag.go
index 085e3f6..549e337 100644
--- a/plumbing/object/tag.go
+++ b/plumbing/object/tag.go
@@ -18,6 +18,8 @@ import (
 // contains meta-information about the tag, including the tagger, tag date and
 // message.
 //
+// Note that this is not used for lightweight tags.
+//
 // https://git-scm.com/book/en/v2/Git-Internals-Git-References#Tags
 type Tag struct {
 	// Hash of the tag.
@@ -26,10 +28,12 @@ type Tag struct {
 	Name string
 	// Tagger is the one who created the tag.
 	Tagger Signature
-	// Message is an arbitrary text message
-	Message    string
+	// Message is an arbitrary text message.
+	Message string
+	// TargetType is the object type of the target.
 	TargetType plumbing.ObjectType
-	Target     plumbing.Hash
+	// Target is the hash of the target object.
+	Target plumbing.Hash
 
 	s storer.EncodedObjectStorer
 }
-- 
cgit