improve doc

Author: posener

examples/godoc/godoc.go

@@ -1,4 +1,4 @@
-// An example that locally serves files from github.com/golang/go/doc
+// An example locally serves files from github.com/golang/go/doc.
 package main
 
 import (

examples/templates/templates.go

@@ -1,4 +1,4 @@
-// An example that locally serves files from github.com/golang/go/doc
+// An example that shows how gitfs helps using template files with Go code smoothly.
 package main
 
 import (

fsutil/fs.go

@@ -1,4 +1,4 @@
-// Package fsutil provides utility functions for http filesystems.
+// Package fsutil provides useful utility functions for http.FileSystem.
 package fsutil
 
 import (
@@ -9,15 +9,17 @@ import (
 	"github.com/kr/fs"
 )
 
-// Walk returns a https://godoc.org/github.com/kr/fs#Walker over an
-// https://golang.org/pkg/net/http/#FileSystem.
+// Walk returns a fs.Walker over http.FileSystem, which enables
+// walking over all files in the filesystem.
+//
+// See https://godoc.org/github.com/kr/fs#Walker for more details.
 func Walk(hfs http.FileSystem, root string) *fs.Walker {
 	return fs.WalkFS(root, fileSystem{hfs})
 }
 
-// FileSystem implements https://godoc.org/github.com/kr/fs#FileSystem over
-// https://golang.org/pkg/net/http/#FileSystem. It can be used to walking
-// over files in the filesystem.
+// FileSystem implements fs.FileSystem over http.FileSystem. 
+//
+// See https://godoc.org/github.com/kr/fs#FileSystem for more details.
 type fileSystem struct {
 	http.FileSystem
 }

fsutil/tmpl.go

@@ -11,7 +11,7 @@ import (
 	"github.com/pkg/errors"
 )
 
-// TmplParse Parse templates from the given filesystem according to the
+// TmplParse parses templates from the given filesystem according to the
 // given paths. If tmpl is not nil, the templates will be added to it.
 // paths must contain at least one path. All paths must exist in the
 // given filesystem.
@@ -30,7 +30,7 @@ func TmplParseGlob(fs http.FileSystem, tmpl *txttmpl.Template, pattern string) (
 	return t.Template, err
 }
 
-// TmplParseHTML Parse HTML templates from the given filesystem according
+// TmplParseHTML parses HTML templates from the given filesystem according
 // to the given paths. If tmpl is not nil, the templates will be added to
 // it. paths must contain at least one path. All paths must exist in the
 // given filesystem.

gitfs.go

@@ -1,50 +1,68 @@
-// Package gitfs enables using static files in Go code without packing them into binary.
+// Package gitfs loads static files in Go code without binary-packing.
 //
-// This package enable loading static files from a remote git repository,
-// in Go code. This files can be used for static serving, template loading,
+// This package enable loading any file from remote git repository in Go code.
+// This files can be used for static serving, template loading, content loading,
 // or anything else.
+//
 // The following features are supported:
 //
 // * Loading of specific version is supported.
+//
 // * For debug purposes, the files can be loaded from local path. The transition
-//   from remote project to local files is smooth.
+// from remote project to local files is smooth.
+//
 // * Project is loaded instantly and files are loaded lazily but only once.
 //
-// Examples
+// Usage
 //
-// To setup a filesystem from a github repository `github.com/x/y` 
-// at a given version v1.2.3 and path "static" inside the project:
+// First, we need to create a filesystem using the `New` function.
+// This function accepts the project path with pattern:
+// `github.com/<owner>/<repo>(/<path>)?(@<ref>)?`.
+// If no `path` is specified, the root of the project will be used.
+// `ref` can be any git branch using `heads/<branch name>` or any
+// git tag using `tags/<tag>`. If the tag is of Semver format, the `tags/`
+// prefix is not required.
+// If no `ref` is specified, the default branch will be used.
+//
+// Here we will load repository `github.com/x/y` at version v1.2.3
+// and internal path "static":
 //
 // 	fs, err := gitfs.New(ctx, "github.com/x/y/[email protected]")
 //
-// Then, reading a file can be done by opening it:
+// Reading a file from the repository can be done using the `Open` method.
+// This function accepts a path, relative to the root of the defined
+// filesystem.
 //
 // 	f, err := fs.Open("index.html")
 //
-// The variable fs, which is of type `http.FileSystem`, can be used to serve
-// static content:
+// The variable `fs` implements `http.FileSystem`, and can be used for anything
+// that accepts it. For example, it can be used for serving static content
+// using the standard library:
 //
 // 	http.Handle("/", http.FileServer(fs))
 //
-// When used with private github repo, you would want to provide
-// an HTTP client with the appropriate credentials. For example,
-// if you have a Github Token in environnement variable `GITHUB_TOKEN`:
+// When used with private github repository, it should be accessed with
+// appropriate credentials. The credentials can be passed by providing an
+// HTTP client. For example, to use a Github Token from environnement
+// variable `GITHUB_TOKEN`:
 //  
 // 	token := os.Getenv("GITHUB_TOKEN")
 // 	client := oauth2.NewClient(
 // 		context.Background(),
 // 		oauth2.StaticTokenSource(&oauth2.Token{AccessToken: token}))
 // 	fs, err := gitfs.New(ctx, "github.com/x/y", gitfs.OptClient(client))
 //
-// There are some useful functions in ./fsutil package. For example, it
-// enables working easily with templates (They can work with any
-// `http.FileSystem`):
+// For debugging purposes, it is easier and faster to use local static
+// content and not remote content that was pushed to the remote repository.
+// This is enabled by the `OptLocal` option. To use this option only in
+// local development and not in production system, it can be used as follow:
+//
+// 	local := os.Getenv("LOCAL_DEBUG")
+// 	fs, err := gitfs.New(ctx, "github.com/x/y", gitfs.OptLocal(local))
 //
-// 	fs, err := gitfs.New(ctx, "github.com/x/y/templates")
-// 	// Handle err...
-// 	tmpl, err := fsutil.TmplParseGlob(fs, nil, "*.gotmpl")
-// 	// Handle err...
-// 	tmpl.ExecuteTemplate(...)
+// Then, running the program with `LOCAL_DEBUG=.` will use local files while
+// running without it will use the remote files. (the value of the environment
+// variable should point to any directory within the github project).
 package gitfs
 
 import (

gitfs_test.go

@@ -11,42 +11,68 @@ import (
 	"github.com/stretchr/testify/require"
 )
 
-func ExampleTest() {
+// With gitfs you can open a remote git repository, and load any file,
+// including non-go files.
+// In this example, the README.md file of a remote repository is loaded.
+func Example_open() {
 	ctx := context.Background()
-	fs, err := New(ctx, "github.com/kelseyhightower/helloworld@tags/3.0.0")
+
+	// The load path is of the form: github.com/<owner>/<repo>(/<path>)?(@<ref>)?.
+	// `ref` can reference any git tag or branch. If github releases are in Semver format,
+	// the `tags/` prefix is not needed in the `ref` part.
+	fs, err := New(ctx, "github.com/kelseyhightower/[email protected]")
 	if err != nil {
 		log.Fatalf("Failed initialize filesystem: %s", err)
 	}
+
+	// Open any file in the github repository, using the `Open` function. Both files
+	// and directory can be opened. The content is not loaded until it is actually being
+	// read. The content is loaded only once.
 	f, err := fs.Open("README.md")
 	if err != nil {
 		log.Fatalf("Failed opening file: %s", err)
 	}
+
+	// Copy the content to stdout.
 	io.Copy(os.Stdout, f)
+
 	// Output: # helloworld
 }
 
-func ExampleTest_templates() {
+// The ./fsutil package is a collection of useful functions that can work with
+// any `http.FileSystem` implementation.
+// For example, here we will use a function that loads go templates from the
+// filesystem.
+func Example_fsutil() {
 	ctx := context.Background()
+
+	// Open a git remote repository `posener/gitfs` in path `examples/templates`.
 	fs, err := New(ctx, "github.com/posener/gitfs/examples/templates")
 	if err != nil {
 		log.Fatalf("Failed initialize filesystem: %s", err)
 	}
 
+	// Use util function that loads all templates according to a glob pattern.
 	tmpls, err := fsutil.TmplParseGlob(fs, nil, "*.gotmpl")
 	if err != nil {
 		log.Fatalf("Failed parsing templates: %s", err)
 	}
+
+	// Execute the template and write to stdout.
 	tmpls.ExecuteTemplate(os.Stdout, "tmpl1.gotmpl", "Foo")
+
 	// Output: Hello, Foo
 }
 
+// Tests not supported repository pattern.
 func TestNew_notSupported(t *testing.T) {
 	t.Parallel()
 	ctx := context.Background()
 	_, err := New(ctx, "git.com/nosuchusername/nosuchproject")
 	require.Error(t, err)
 }
 
+// Tests loading of local repository.
 func TestNew_local(t *testing.T) {
 	t.Parallel()
 	ctx := context.Background()

goreadme.json

@@ -0,0 +1,10 @@
+{
+	"recursive": true,
+	"badges": {
+		"goreadme": true,
+		"travis_ci": true,
+		"code_cov": true,
+		"golang_ci": true,
+		"go_doc": true
+	}
+}

internal/githubfs/githubtree.go

@@ -17,7 +17,7 @@ import (
 
 var (
 	reGithubProject = regexp.MustCompile(`^github\.com/([^@/]+)/([^@/]+)(/([^@]*))?(@([^#]+))?$`)
-	reSemver        = regexp.MustCompile(`^v\d+(\.\d+){0,2}$`)
+	reSemver        = regexp.MustCompile(`^v?\d+(\.\d+){0,2}$`)
 )
 
 type project struct {

internal/githubfs/githubtree_test.go

@@ -53,6 +53,9 @@ func TestGithubProjectProperties(t *testing.T) {
 		{path: "github.com/x/y@v1", wantOwner: "x", wantRepo: "y", wantRef: "tags/v1"},
 		{path: "github.com/x/[email protected]", wantOwner: "x", wantRepo: "y", wantRef: "tags/v1.2"},
 		{path: "github.com/x/[email protected]", wantOwner: "x", wantRepo: "y", wantRef: "tags/v1.2.3"},
+		{path: "github.com/x/y@1", wantOwner: "x", wantRepo: "y", wantRef: "tags/1"},
+		{path: "github.com/x/[email protected]", wantOwner: "x", wantRepo: "y", wantRef: "tags/1.2"},
+		{path: "github.com/x/[email protected]", wantOwner: "x", wantRepo: "y", wantRef: "tags/1.2.3"},
 		{path: "github.com/x/y/static/path", wantOwner: "x", wantRepo: "y", wantPath: "static/path/"},
 		{path: "github.com/x/y/[email protected]", wantOwner: "x", wantRepo: "y", wantRef: "tags/v1.2.3", wantPath: "static/"},
 	}
@@ -85,7 +88,8 @@ func TestGithubProjectProperties_error(t *testing.T) {
 		// Invalid semvers
 		"github.com/x/y@v1.",
 		"github.com/x/[email protected]",
-		"github.com/x/[email protected]",
+		"github.com/x/y@1.",
+		"github.com/x/[email protected]",
 	}
 
 	for _, path := range paths {