documentation changes

23 files changed, 169 insertions, 82 deletions

diff --git a/README.md b/README.md
index 5a379fc..00f88f5 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # go-git [![GoDoc](https://godoc.org/srcd.works/go-git.v4?status.svg)](https://godoc.org/srcd.works/go-git.v4) [![Build Status](https://travis-ci.org/src-d/go-git.svg)](https://travis-ci.org/src-d/go-git) [![codecov.io](https://codecov.io/github/src-d/go-git/coverage.svg)](https://codecov.io/github/src-d/go-git) [![codebeat badge](https://codebeat.co/badges/b6cb2f73-9e54-483d-89f9-4b95a911f40c)](https://codebeat.co/projects/github-com-src-d-go-git)
 
-A low level and highly extensible git implementation in **pure Go**.
+A highly extensible git implementation in **pure Go**.
 
 *go-git* aims to reach the completeness of [libgit2](https://libgit2.github.com/) or [jgit](http://www.eclipse.org/jgit/), nowadays covers the **majority** of the plumbing **read operations** and **some** of the main **write operations**, but lacks the main porcelain operations such as merges.
 
@@ -27,7 +27,7 @@ go get -u srcd.works/go-git.v4/...
 Examples
 --------
 
-> Please note that the functions `CheckIfError` and `Info` used in the examples are from the [examples package](https://github.com/src-d/go-git/blob/master/examples/common.go#L17) just to be used in the examples.
+> Please note that the functions `CheckIfError` and `Info` used in the examples are from the [examples package](https://github.com/src-d/go-git/blob/master/_examples/common.go#L17) just to be used in the examples.
 
 
 ### Basic example
@@ -109,7 +109,7 @@ Date:   Fri Nov 11 13:23:22 2016 +0100
 ...
 ```
 
-You can find this [example](examples/log/main.go) and many other at the [examples](examples) folder
+You can find this [example](_examples/log/main.go) and many other at the [examples](_examples) folder
 
 Contribute
 ----------
diff --git a/examples/README.md b/_examples/README.md
index 334664f..334664f 100644
--- a/examples/README.md
+++ b/_examples/README.md
diff --git a/examples/clone/main.go b/_examples/clone/main.go
index 7d48c40..7d48c40 100644
--- a/examples/clone/main.go
+++ b/_examples/clone/main.go
diff --git a/examples/common.go b/_examples/common.go
index 971b0f6..971b0f6 100644
--- a/examples/common.go
+++ b/_examples/common.go
diff --git a/examples/common_test.go b/_examples/common_test.go
index b218e07..b218e07 100644
--- a/examples/common_test.go
+++ b/_examples/common_test.go
diff --git a/examples/custom_http/main.go b/_examples/custom_http/main.go
index ee8b96b..ee8b96b 100644
--- a/examples/custom_http/main.go
+++ b/_examples/custom_http/main.go
diff --git a/examples/log/main.go b/_examples/log/main.go
index 5eb4763..486e8c9 100644
--- a/examples/log/main.go
+++ b/_examples/log/main.go
@@ -12,7 +12,9 @@ func main() {
 	// Clones the given repository, creating the remote, the local branches
 	// and fetching the objects, everything in memory:
 	Info("git clone https://github.com/src-d/go-siva")
-	r, err := git.Clone(memory.NewStorage(), nil, &git.CloneOptions{URL: "https://github.com/src-d/go-siva"})
+	r, err := git.Clone(memory.NewStorage(), nil, &git.CloneOptions{
+		URL: "https://github.com/src-d/go-siva",
+	})
 	CheckIfError(err)
 
 	// Gets the HEAD history from HEAD, just like does:
diff --git a/examples/open/main.go b/_examples/open/main.go
index aa51935..aa51935 100644
--- a/examples/open/main.go
+++ b/_examples/open/main.go
diff --git a/examples/progress/main.go b/_examples/progress/main.go
index a06de54..a06de54 100644
--- a/examples/progress/main.go
+++ b/_examples/progress/main.go
diff --git a/examples/push/main.go b/_examples/push/main.go
index cfae064..cfae064 100644
--- a/examples/push/main.go
+++ b/_examples/push/main.go
diff --git a/examples/remotes/main.go b/_examples/remotes/main.go
index 362244b..362244b 100644
--- a/examples/remotes/main.go
+++ b/_examples/remotes/main.go
diff --git a/examples/showcase/main.go b/_examples/showcase/main.go
index e70de61..e70de61 100644
--- a/examples/showcase/main.go
+++ b/_examples/showcase/main.go
diff --git a/blame.go b/blame.go
index 72f0c9a..0518ff5 100644
--- a/blame.go
+++ b/blame.go
@@ -50,20 +50,16 @@ type BlameResult struct {
 // All this work is done in the assignOrigin function which holds all
 // the internal relevant data in a "blame" struct, that is not
 // exported.
-//
-// TODO: ways to improve the efficiency of this function:
-//
-// 1. Improve revlist
-//
-// 2. Improve how to traverse the history (example a backward
-// traversal will be much more efficient)
-//
-// TODO: ways to improve the function in general:
-//
-// 1. Add memoization between revlist and assign.
-//
-// 2. It is using much more memory than needed, see the TODOs below.
 func Blame(c *object.Commit, path string) (*BlameResult, error) {
+	// TODO: ways to improve the efficiency of this function:
+	// 1. Improve revlist
+	// 2. Improve how to traverse the history (example a backward traversal will
+	// be much more efficient)
+	//
+	// TODO: ways to improve the function in general:
+	// 1. Add memoization between revlist and assign.
+	// 2. It is using much more memory than needed, see the TODOs below.
+
 	b := new(blame)
 	b.fRev = c
 	b.path = path
diff --git a/common.go b/common.go
index 623a2f7..1a05dc3 100644
--- a/common.go
+++ b/common.go
@@ -8,9 +8,9 @@ import (
 )
 
 // Storer is a generic storage of objects, references and any information
-// related to a particular repository. Some Storer implementations persist the
-// information in a system directory (such as `.git`) and others
-// implementations are in memory being ephemeral
+// related to a particular repository. The package srcd.works/go-git.v4/storage
+// contains two implementation a filesystem base implementation (such as `.git`)
+// and a memory implementations being ephemeral
 type Storer interface {
 	storer.EncodedObjectStorer
 	storer.ReferenceStorer
diff --git a/doc.go b/doc.go
index d304938..7f57cbd 100644
--- a/doc.go
+++ b/doc.go
@@ -1,37 +1,10 @@
-// Package git is a low level and highly extensible git client library for
-// reading repositories from git servers.  It is written in Go from scratch,
-// without any C dependencies.
+// A highly extensible git implementation in pure Go.
 //
-// We have been following the open/close principle in its design to facilitate
-// extensions.
+// go-git aims to reach the completeness of libgit2 or jgit, nowadays covers the
+// majority of the plumbing read operations and some of the main write
+// operations, but lacks the main porcelain operations such as merges.
 //
-// Small example extracting the commits from a repository:
-//
-//     func ExampleBasic_printCommits() {
-//         r := git.NewMemoryRepository()
-//         o := &git.CloneOptions{
-//             URL: "https://github.com/src-d/go-git",
-//         }
-//         if err := r.Clone(o); err != nil {
-//             panic(err)
-//         }
-//
-//         iter, err := r.Commits()
-//         if err != nil {
-//             panic(err)
-//         }
-//         defer iter.Close()
-//
-//         for {
-//             commit, err := iter.Next()
-//             if err != nil {
-//                 if err == io.EOF {
-//                     break
-//                 }
-//                 panic(err)
-//             }
-//
-//             fmt.Println(commit)
-//         }
-//    }
+// It is highly extensible, we have been following the open/close principle in
+// its design to facilitate extensions, mainly focusing the efforts on the
+// persistence of the objects.
 package git // import "srcd.works/go-git.v4"
diff --git a/example_test.go b/example_test.go
new file mode 100644
index 0000000..a45225a
--- /dev/null
+++ b/example_test.go
@@ -0,0 +1,112 @@
+package git_test
+
+import (
+	"fmt"
+	"io"
+	"io/ioutil"
+	"log"
+	"os"
+	"path/filepath"
+
+	"srcd.works/go-billy.v1/memfs"
+	git "srcd.works/go-git.v4"
+	"srcd.works/go-git.v4/config"
+	"srcd.works/go-git.v4/plumbing"
+	"srcd.works/go-git.v4/storage/memory"
+)
+
+func ExampleClone() {
+	// Filesystem abstraction based on memory
+	fs := memfs.New()
+	// Git objects storer based on memory
+	storer := memory.NewStorage()
+
+	// Clones the repository into the worktree (fs) and storer all the .git
+	// content into the storer
+	_, _ = git.Clone(storer, fs, &git.CloneOptions{
+		URL: "https://github.com/git-fixtures/basic.git",
+	})
+
+	// Prints the content of the CHANGELOG file from the cloned repository
+	changelog, _ := fs.Open("CHANGELOG")
+
+	io.Copy(os.Stdout, changelog)
+	// Output: Initial changelog
+}
+
+func ExamplePlainClone() {
+	// Tempdir to clone the repository
+	dir, err := ioutil.TempDir("", "clone-example")
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	defer os.RemoveAll(dir) // clean up
+
+	// Clones the repository into the given dir, just as a normal git clone does
+	_, err = git.PlainClone(dir, false, &git.CloneOptions{
+		URL: "https://github.com/git-fixtures/basic.git",
+	})
+
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	// Prints the content of the CHANGELOG file from the cloned repository
+	changelog, err := os.Open(filepath.Join(dir, "CHANGELOG"))
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	io.Copy(os.Stdout, changelog)
+	// Output: Initial changelog
+}
+
+func ExampleRepository_References() {
+	r, _ := git.Clone(memory.NewStorage(), nil, &git.CloneOptions{
+		URL: "https://github.com/git-fixtures/basic.git",
+	})
+
+	// simulating a git show-ref
+	refs, _ := r.References()
+	refs.ForEach(func(ref *plumbing.Reference) error {
+		if ref.Type() == plumbing.HashReference {
+			fmt.Println(ref)
+		}
+
+		return nil
+	})
+
+	// Example Output:
+	// 6ecf0ef2c2dffb796033e5a02219af86ec6584e5 refs/remotes/origin/master
+	// e8d3ffab552895c19b9fcf7aa264d277cde33881 refs/remotes/origin/branch
+	// 6ecf0ef2c2dffb796033e5a02219af86ec6584e5 refs/heads/master
+
+}
+
+func ExampleRepository_CreateRemote() {
+	r, _ := git.Init(memory.NewStorage(), nil)
+
+	// Add a new remote, with the default fetch refspec
+	_, err := r.CreateRemote(&config.RemoteConfig{
+		Name: "example",
+		URL:  "https://github.com/git-fixtures/basic.git",
+	})
+
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	list, err := r.Remotes()
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	for _, r := range list {
+		fmt.Println(r)
+	}
+
+	// Example Output:
+	// example https://github.com/git-fixtures/basic.git (fetch)
+	// example https://github.com/git-fixtures/basic.git (push)
+}
diff --git a/plumbing/format/index/decoder.go b/plumbing/format/index/decoder.go
index 1a52fcd..59581da 100644
--- a/plumbing/format/index/decoder.go
+++ b/plumbing/format/index/decoder.go
@@ -207,9 +207,10 @@ func (d *Decoder) padEntry(idx *Index, e *Entry, read int) error {
 	return nil
 }
 
-// TODO: support 'Split index' and 'Untracked cache' extensions, take in count
-//       that they are not supported by jgit or libgit
 func (d *Decoder) readExtensions(idx *Index) error {
+	// TODO: support 'Split index' and 'Untracked cache' extensions, take in
+	// count that they are not supported by jgit or libgit
+
 	var expected []byte
 	var err error
 
diff --git a/plumbing/protocol/packp/srvresp.go b/plumbing/protocol/packp/srvresp.go
index 0e027b4..95e1e57 100644
--- a/plumbing/protocol/packp/srvresp.go
+++ b/plumbing/protocol/packp/srvresp.go
@@ -13,8 +13,8 @@ import (
 const ackLineLen = 44
 
 // ServerResponse object acknowledgement from upload-pack service
-// TODO: implement support for multi_ack or multi_ack_detailed responses
 type ServerResponse struct {
+	// TODO: implement support for multi_ack or multi_ack_detailed responses
 	ACKs []plumbing.Hash
 }
 
diff --git a/plumbing/protocol/packp/updreq.go b/plumbing/protocol/packp/updreq.go
index b685999..4337ace 100644
--- a/plumbing/protocol/packp/updreq.go
+++ b/plumbing/protocol/packp/updreq.go
@@ -15,9 +15,8 @@ var (
 
 // ReferenceUpdateRequest values represent reference upload requests.
 // Values from this type are not zero-value safe, use the New function instead.
-//
-// TODO: Add support for push-cert
 type ReferenceUpdateRequest struct {
+	// TODO: Add support for push-cert
 	Capabilities *capability.List
 	Commands     []*Command
 	Shallow      *plumbing.Hash
diff --git a/plumbing/transport/server/server.go b/plumbing/transport/server/server.go
index 832c127..79b64a1 100644
--- a/plumbing/transport/server/server.go
+++ b/plumbing/transport/server/server.go
@@ -72,8 +72,8 @@ func (s *session) Close() error {
 	return nil
 }
 
-//TODO: deprecate
 func (s *session) SetAuth(transport.AuthMethod) error {
+	//TODO: deprecate
 	return nil
 }
 
diff --git a/remote.go b/remote.go
index 5ab71df..2d243e9 100644
--- a/remote.go
+++ b/remote.go
@@ -54,12 +54,12 @@ func (r *Remote) Fetch(o *FetchOptions) error {
 
 // Push performs a push to the remote. Returns NoErrAlreadyUpToDate if the
 // remote was already up-to-date.
-//
-// TODO: Support deletes.
-// TODO: Support pushing tags.
-// TODO: Check if force update is given, otherwise reject non-fast forward.
-// TODO: Sideband support
 func (r *Remote) Push(o *PushOptions) (err error) {
+	// TODO: Support deletes.
+	// TODO: Support pushing tags.
+	// TODO: Check if force update is given, otherwise reject non-fast forward.
+	// TODO: Sideband suppor
+
 	if o.RemoteName == "" {
 		o.RemoteName = r.c.Name
 	}
diff --git a/repository.go b/repository.go
index 5511ba6..4a65f46 100644
--- a/repository.go
+++ b/repository.go
@@ -26,7 +26,7 @@ var (
 	ErrIsBareRepository        = errors.New("worktree not available in a bare repository")
 )
 
-// Repository giturl string, auth common.AuthMethod repository struct
+// Repository represents a git repository
 type Repository struct {
 	r  map[string]*Remote
 	s  Storer
@@ -119,7 +119,7 @@ func PlainInit(path string, isBare bool) (*Repository, error) {
 	return Init(s, wt)
 }
 
-// PlainOpen opens a git repository from the given path. It detects is the
+// PlainOpen opens a git repository from the given path. It detects if the
 // repository is bare or a normal one. If the path doesn't contain a valid
 // repository ErrRepositoryNotExists is returned
 func PlainOpen(path string) (*Repository, error) {
@@ -185,7 +185,7 @@ func (r *Repository) Remote(name string) (*Remote, error) {
 	return newRemote(r.s, c), nil
 }
 
-// Remotes return all the remotes
+// Remotes returns a list with all the remotes
 func (r *Repository) Remotes() ([]*Remote, error) {
 	cfg, err := r.s.Config()
 	if err != nil {
@@ -511,12 +511,13 @@ func (r *Repository) Push(o *PushOptions) error {
 	return remote.Push(o)
 }
 
-// Commit return the commit with the given hash
+// Commit return a Commit with the given hash. If not found
+// plumbing.ErrObjectNotFound is returned
 func (r *Repository) Commit(h plumbing.Hash) (*object.Commit, error) {
 	return object.GetCommit(r.s, h)
 }
 
-// Commits decode the objects into commits
+// Commits returns an unsorted CommitIter with all the commits in the repository
 func (r *Repository) Commits() (*object.CommitIter, error) {
 	iter, err := r.s.IterEncodedObjects(plumbing.CommitObject)
 	if err != nil {
@@ -526,12 +527,13 @@ func (r *Repository) Commits() (*object.CommitIter, error) {
 	return object.NewCommitIter(r.s, iter), nil
 }
 
-// Tree return the tree with the given hash
+// Tree return a Tree with the given hash. If not found
+// plumbing.ErrObjectNotFound is returned
 func (r *Repository) Tree(h plumbing.Hash) (*object.Tree, error) {
 	return object.GetTree(r.s, h)
 }
 
-// Trees decodes the objects into trees
+// Trees returns an unsorted TreeIter with all the trees in the repository
 func (r *Repository) Trees() (*object.TreeIter, error) {
 	iter, err := r.s.IterEncodedObjects(plumbing.TreeObject)
 	if err != nil {
@@ -541,12 +543,13 @@ func (r *Repository) Trees() (*object.TreeIter, error) {
 	return object.NewTreeIter(r.s, iter), nil
 }
 
-// Blob returns the blob with the given hash
+// Blob returns a Blob with the given hash. If not found
+// plumbing.ErrObjectNotFound is returne
 func (r *Repository) Blob(h plumbing.Hash) (*object.Blob, error) {
 	return object.GetBlob(r.s, h)
 }
 
-// Blobs decodes the objects into blobs
+// Blobs returns an unsorted BlobIter with all the blobs in the repository
 func (r *Repository) Blobs() (*object.BlobIter, error) {
 	iter, err := r.s.IterEncodedObjects(plumbing.BlobObject)
 	if err != nil {
@@ -556,13 +559,14 @@ func (r *Repository) Blobs() (*object.BlobIter, error) {
 	return object.NewBlobIter(r.s, iter), nil
 }
 
-// Tag returns a tag with the given hash.
+// Tag returns a Tag with the given hash. If not found
+// plumbing.ErrObjectNotFound is returned
 func (r *Repository) Tag(h plumbing.Hash) (*object.Tag, error) {
 	return object.GetTag(r.s, h)
 }
 
-// Tags returns a object.TagIter that can step through all of the annotated tags
-// in the repository.
+// Tags returns a unsorted TagIter that can step through all of the annotated
+// tags in the repository.
 func (r *Repository) Tags() (*object.TagIter, error) {
 	iter, err := r.s.IterEncodedObjects(plumbing.TagObject)
 	if err != nil {
@@ -572,7 +576,8 @@ func (r *Repository) Tags() (*object.TagIter, error) {
 	return object.NewTagIter(r.s, iter), nil
 }
 
-// Object returns an object with the given hash.
+// Object returns an Object with the given hash. If not found
+// plumbing.ErrObjectNotFound is returned
 func (r *Repository) Object(t plumbing.ObjectType, h plumbing.Hash) (object.Object, error) {
 	obj, err := r.s.EncodedObject(t, h)
 	if err != nil {
@@ -586,8 +591,7 @@ func (r *Repository) Object(t plumbing.ObjectType, h plumbing.Hash) (object.Obje
 	return object.DecodeObject(r.s, obj)
 }
 
-// Objects returns an object.ObjectIter that can step through all of the annotated tags
-// in the repository.
+// Objects returns an unsorted BlobIter with all the objects in the repository
 func (r *Repository) Objects() (*object.ObjectIter, error) {
 	iter, err := r.s.IterEncodedObjects(plumbing.AnyObject)
 	if err != nil {
@@ -614,7 +618,7 @@ func (r *Repository) Reference(name plumbing.ReferenceName, resolved bool) (
 	return r.s.Reference(name)
 }
 
-// References returns a ReferenceIter for all references.
+// References returns an unsorted ReferenceIter for all references.
 func (r *Repository) References() (storer.ReferenceIter, error) {
 	return r.s.IterReferences()
 }
diff --git a/repository_test.go b/repository_test.go
index c9021a2..76ba9f3 100644
--- a/repository_test.go
+++ b/repository_test.go
@@ -9,8 +9,8 @@ import (
 	"path/filepath"
 	"strings"
 
-	"srcd.works/go-git.v4/config"
 	"github.com/src-d/go-git-fixtures"
+	"srcd.works/go-git.v4/config"
 	"srcd.works/go-git.v4/plumbing"
 	"srcd.works/go-git.v4/plumbing/object"
 	"srcd.works/go-git.v4/storage/filesystem"