From 305f28004ecbc03ea353437cf4c76423d93fbbd8 Mon Sep 17 00:00:00 2001
From: Antonio Jesus Navarro Perez <antonio@sourced.tech>
Date: Tue, 28 Feb 2017 11:56:10 +0100
Subject: _examples: improve documentation

---
 _examples/README.md        | 5 +++--
 _examples/clone/main.go    | 1 +
 _examples/log/main.go      | 5 +++++
 _examples/open/main.go     | 1 +
 _examples/progress/main.go | 1 +
 _examples/push/main.go     | 3 +++
 _examples/remotes/main.go  | 7 +++++++
 _examples/showcase/main.go | 8 ++++++++
 8 files changed, 29 insertions(+), 2 deletions(-)

diff --git a/_examples/README.md b/_examples/README.md
index d027d50..d6f3e55 100644
--- a/_examples/README.md
+++ b/_examples/README.md
@@ -6,9 +6,10 @@ Here you can find a list of annotated _go-git_ examples:
 - [showcase](showcase/main.go) - A small showcase of the capabilities of _go-git_
 - [open](open/main.go) - Opening a existing repository cloned by _git_
 - [clone](clone/main.go) - Cloning a repository
+- [log](log/main.go) - Emulate `git log` command output iterating all the commit history from HEAD reference
 - [remotes](remotes/main.go) - Working with remotes: adding, removing, etc
-- [progress](progress/main.go) - Priting the progress information from the sideband
-
+- [progress](progress/main.go) - Printing the progress information from the sideband
+- [push](push/main.go) - Push repository to default remote (origin)
 ### Advanced
 - [custom_http](custom_http/main.go) - Replacing the HTTP client using a custom one
 - [storage](storage/README.md) - Implementing a custom storage system
diff --git a/_examples/clone/main.go b/_examples/clone/main.go
index bcdb6a9..27d043b 100644
--- a/_examples/clone/main.go
+++ b/_examples/clone/main.go
@@ -8,6 +8,7 @@ import (
 	. "srcd.works/go-git.v4/_examples"
 )
 
+// Basic example of how to clone a repository using clone options.
 func main() {
 	CheckArgs("<url>", "<directory>")
 	url := os.Args[1]
diff --git a/_examples/log/main.go b/_examples/log/main.go
index eded360..da856ac 100644
--- a/_examples/log/main.go
+++ b/_examples/log/main.go
@@ -8,6 +8,11 @@ import (
 	"srcd.works/go-git.v4/storage/memory"
 )
 
+// Example of how to:
+// - Clone a repository into memory
+// - Get the HEAD reference
+// - Using the HEAD reference, obtain the commit this reference is pointing to
+// - Using the commit, obtain its history and print it
 func main() {
 	// Clones the given repository, creating the remote, the local branches
 	// and fetching the objects, everything in memory:
diff --git a/_examples/open/main.go b/_examples/open/main.go
index 063c277..9174588 100644
--- a/_examples/open/main.go
+++ b/_examples/open/main.go
@@ -8,6 +8,7 @@ import (
 	. "srcd.works/go-git.v4/_examples"
 )
 
+// Open an existing repository in a specific folder.
 func main() {
 	CheckArgs("<path>")
 	path := os.Args[1]
diff --git a/_examples/progress/main.go b/_examples/progress/main.go
index 81546c3..6d68f84 100644
--- a/_examples/progress/main.go
+++ b/_examples/progress/main.go
@@ -7,6 +7,7 @@ import (
 	. "srcd.works/go-git.v4/_examples"
 )
 
+// Example of how to show the progress when you do a basic clone operation.
 func main() {
 	CheckArgs("<url>", "<directory>")
 	url := os.Args[1]
diff --git a/_examples/push/main.go b/_examples/push/main.go
index aaec5a3..7c23642 100644
--- a/_examples/push/main.go
+++ b/_examples/push/main.go
@@ -7,6 +7,8 @@ import (
 	. "srcd.works/go-git.v4/_examples"
 )
 
+// Example of how to open a repository in a specific path, and do a push to
+// his default remote (origin).
 func main() {
 	CheckArgs("<repository-path>")
 	path := os.Args[1]
@@ -15,6 +17,7 @@ func main() {
 	CheckIfError(err)
 
 	Info("git push")
+	// push using default push options
 	err = r.Push(&git.PushOptions{})
 	CheckIfError(err)
 }
diff --git a/_examples/remotes/main.go b/_examples/remotes/main.go
index 9537fea..8c59a67 100644
--- a/_examples/remotes/main.go
+++ b/_examples/remotes/main.go
@@ -10,6 +10,13 @@ import (
 	"srcd.works/go-git.v4/storage/memory"
 )
 
+// Example of how to:
+// - Create a new repository into memory
+// - Create a new remote called "example"
+// - List remotes and print them
+// - Pull using the new remote "example"
+// - Iterate again the references, but only showing hash references, not simbolic ones
+// - Remove remote "example"
 func main() {
 	// Create a new repository
 	Info("git init")
diff --git a/_examples/showcase/main.go b/_examples/showcase/main.go
index 7772d84..82c2acf 100644
--- a/_examples/showcase/main.go
+++ b/_examples/showcase/main.go
@@ -11,6 +11,14 @@ import (
 	. "srcd.works/go-git.v4/_examples"
 )
 
+// Example of an specific use case:
+// - Clone a repository in a specific path
+// - Get the HEAD reference
+// - Using the HEAD reference, obtain the commit this reference is pointing to
+// - Print the commit content
+// - Using the commit, iterate all its files and print them
+// - Print all the commit history with commit messages, short hash and the
+// first line of the commit message
 func main() {
 	CheckArgs("<url> <path>")
 	url := os.Args[1]
-- 
cgit