_examples: improve documentation (fix #238)

_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

_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]

_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:

_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]

_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]

_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 push to
+// its 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 options
 	err = r.Push(&git.PushOptions{})
 	CheckIfError(err)
 }

_examples/remotes/main.go

@@ -10,6 +10,13 @@ import (
 	"srcd.works/go-git.v4/storage/memory"
 )
 
+// Example of how to:
+// - Create a new in-memory repository
+// - Create a new remote named "example"
+// - List remotes and print them
+// - Pull using the new remote "example"
+// - Iterate the references again, but only showing hash references, not symbolic ones
+// - Remove remote "example"
 func main() {
 	// Create a new repository
 	Info("git init")

_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]