Add godocs

README.md

@@ -1,5 +1,7 @@
 # flagvar 
 
+[![](https://godoc.org/github.com/sgreben/flagvar?status.svg)](http://godoc.org/github.com/sgreben/flagvar) [![](https://goreportcard.com/badge/github.com/sgreben/flagvar/goreportcard?style=flat-square)](https://goreportcard.com/github.com/sgreben)
+
 A collection of CLI argument types for the `flag` package. 
 
 ## Example
@@ -60,6 +62,7 @@ Here's a compact overview:
 | [Enums](https://godoc.org/github.com/sgreben/flagvar#Enums)       | apple              | []string                             |
 | [EnumSet](https://godoc.org/github.com/sgreben/flagvar#EnumSet)     | apple              | []string                             |
 | [File](https://godoc.org/github.com/sgreben/flagvar#File)        | ./README.md        | string                               |
+| [Files](https://godoc.org/github.com/sgreben/flagvar#Files)        | ./README.md        | string                               |
 | [Floats](https://godoc.org/github.com/sgreben/flagvar#Floats)      | 1.234              | []float64                            |
 | [Glob](https://godoc.org/github.com/sgreben/flagvar#Glob)        | src/**.js          | glob.Glob                            |
 | [Globs](https://godoc.org/github.com/sgreben/flagvar#Globs)       | src/**.js          | glob.Glob                            |
@@ -75,4 +78,5 @@ Here's a compact overview:
 | [URL](https://godoc.org/github.com/sgreben/flagvar#URL)         | https://github.com | *url.URL                             |
 | [URLs](https://godoc.org/github.com/sgreben/flagvar#URLs)        | https://github.com | []*url.URL                           |
 | [Wrap](https://godoc.org/github.com/sgreben/flagvar#Wrap)        |                    |                                      |
-| [WrapFunc](https://godoc.org/github.com/sgreben/flagvar#WrapFunc)    |                    |                                      |
+| [WrapFunc](https://godoc.org/github.com/sgreben/flagvar#WrapFunc)    |                    |                                      |
+| [WrapPointer](https://godoc.org/github.com/sgreben/flagvar#WrapPointer)    |                    |                                      |

assignment.go

@@ -5,11 +5,14 @@ import (
 	"strings"
 )
 
+// KV is a key-value pair of strings
 type KV struct {
 	Key   string
 	Value string
 }
 
+// Assignment is a `flag.Value` for `KEY=VALUE` arguments.
+// The value of the `Separator` field is used instead  of `"="` when set.
 type Assignment struct {
 	Separator string
 
@@ -39,6 +42,8 @@ func (fv *Assignment) String() string {
 	return fv.Text
 }
 
+// Assignments is a `flag.Value` for `KEY=VALUE` arguments.
+// The value of the `Separator` field is used instead  of `"="` when set.
 type Assignments struct {
 	Separator string
 

enum.go

@@ -5,6 +5,8 @@ import (
 	"strings"
 )
 
+// Enum is a `flag.Value` for one-of-a-fixed-set string arguments.
+// The value of the `Choices` field defines the valid choices.
 type Enum struct {
 	Choices []string
 
@@ -26,6 +28,8 @@ func (fv *Enum) String() string {
 	return fv.Value
 }
 
+// Enums is a `flag.Value` for one-of-a-fixed-set string arguments.
+// The value of the `Choices` field defines the valid choices.
 type Enums struct {
 	Choices []string
 
@@ -47,6 +51,9 @@ func (fv *Enums) String() string {
 	return strings.Join(fv.Values, ",")
 }
 
+// EnumSet is a `flag.Value` for one-of-a-fixed-set string arguments.
+// Only distinct values are returned.
+// The value of the `Choices` field defines the valid choices.
 type EnumSet struct {
 	Choices []string
 

file.go

@@ -1,7 +1,13 @@
 package flagvar
 
-import "os"
+import (
+	"os"
+	"strings"
+)
 
+// File is a `flag.Value` for file path arguments.
+// By default, any errors from os.Stat are returned.
+// Alternatively, the value of the `Validate` field is used as a validator when specified.
 type File struct {
 	Validate func(os.FileInfo, error) error
 
@@ -11,6 +17,7 @@ type File struct {
 // Set is flag.Value.Set
 func (fv *File) Set(v string) error {
 	info, err := os.Stat(v)
+	fv.Value = v
 	if fv.Validate != nil {
 		return fv.Validate(info, err)
 	}
@@ -20,3 +27,26 @@ func (fv *File) Set(v string) error {
 func (fv *File) String() string {
 	return fv.Value
 }
+
+// Files is a `flag.Value` for file path arguments.
+// By default, any errors from os.Stat are returned.
+// Alternatively, the value of the `Validate` field is used as a validator when specified.
+type Files struct {
+	Validate func(os.FileInfo, error) error
+
+	Values []string
+}
+
+// Set is flag.Value.Set
+func (fv *Files) Set(v string) error {
+	info, err := os.Stat(v)
+	fv.Values = append(fv.Values, v)
+	if fv.Validate != nil {
+		return fv.Validate(info, err)
+	}
+	return err
+}
+
+func (fv *Files) String() string {
+	return strings.Join(fv.Values, ",")
+}

floats.go

@@ -5,6 +5,8 @@ import (
 	"strings"
 )
 
+// Floats is a `flag.Value` for float arguments.
+// The `BitSize` field is used for parsing when set.
 type Floats struct {
 	BitSize int
 

glob.go

@@ -7,6 +7,7 @@ import (
 	"github.com/gobwas/glob"
 )
 
+// Glob is a `flag.Value` for glob syntax arguments.
 type Glob struct {
 	Value glob.Glob
 	Text  string
@@ -26,6 +27,7 @@ func (fv *Glob) String() string {
 	return fv.Text
 }
 
+// Globs is a `flag.Value` for glob syntax arguments.
 type Globs struct {
 	Values []glob.Glob
 	Texts  []string

ints.go

@@ -5,6 +5,8 @@ import (
 	"strings"
 )
 
+// Ints is a `flag.Value` for `int` arguments.
+// The `Base` and `BitSize` fields are used for parsing when set.
 type Ints struct {
 	Base    int
 	BitSize int

json.go

@@ -5,6 +5,7 @@ import (
 	"strings"
 )
 
+// JSON is a `flag.Value` for JSON arguments.
 type JSON struct {
 	Value interface{}
 	Text  string
@@ -20,6 +21,7 @@ func (fv *JSON) String() string {
 	return fv.Text
 }
 
+// JSONs is a `flag.Value` for JSON arguments.
 type JSONs struct {
 	Values []interface{}
 	Texts  []string

string.go

@@ -2,6 +2,7 @@ package flagvar
 
 import "strings"
 
+// Strings is a `flag.Value` for `string` arguments.
 type Strings struct {
 	Values []string
 }
@@ -16,6 +17,8 @@ func (fv *Strings) String() string {
 	return strings.Join(fv.Values, ",")
 }
 
+// StringSet is a `flag.Value` for `string` arguments.
+// Only distinct values are returned.
 type StringSet struct {
 	Value map[string]bool
 }

template.go

@@ -5,6 +5,8 @@ import (
 	"text/template"
 )
 
+// Template is a `flag.Value` for `text.Template` arguments.
+// The value of the `Root` field is used as a root template when specified.
 type Template struct {
 	Root *template.Template
 
@@ -29,6 +31,8 @@ func (fv *Template) String() string {
 	return fv.Text
 }
 
+// Templates is a `flag.Value` for `text.Template` arguments.
+// The value of the `Root` field is used as a root template when specified.
 type Templates struct {
 	Root *template.Template
 

time.go

@@ -5,6 +5,9 @@ import (
 	"time"
 )
 
+// Time is a `flag.Value` for `time.Time` arguments.
+// The value of the `Layout` field is used for parsing when specified.
+// Otherwise, `time.RFC3339` is used.
 type Time struct {
 	Layout string
 
@@ -14,7 +17,11 @@ type Time struct {
 
 // Set is flag.Value.Set
 func (fv *Time) Set(v string) error {
-	t, err := time.Parse(fv.Layout, v)
+	layout := fv.Layout
+	if layout == "" {
+		layout = time.RFC3339
+	}
+	t, err := time.Parse(layout, v)
 	if err == nil {
 		fv.Text = v
 		fv.Value = t
@@ -26,6 +33,9 @@ func (fv *Time) String() string {
 	return fv.Text
 }
 
+// Times is a `flag.Value` for `time.Time` arguments.
+// The value of the `Layout` field is used for parsing when specified.
+// Otherwise, `time.RFC3339` is used.
 type Times struct {
 	Layout string
 
@@ -35,7 +45,11 @@ type Times struct {
 
 // Set is flag.Value.Set
 func (fv *Times) Set(v string) error {
-	t, err := time.Parse(fv.Layout, v)
+	layout := fv.Layout
+	if layout == "" {
+		layout = time.RFC3339
+	}
+	t, err := time.Parse(layout, v)
 	if err == nil {
 		fv.Texts = append(fv.Texts, v)
 		fv.Values = append(fv.Values, t)

url.go

@@ -5,6 +5,7 @@ import (
 	"strings"
 )
 
+// URL is a `flag.Value` for `url.URL` arguments.
 type URL struct {
 	Value *url.URL
 	Text  string
@@ -24,6 +25,7 @@ func (fv *URL) String() string {
 	return fv.Text
 }
 
+// URLs is a `flag.Value` for `url.URL` arguments.
 type URLs struct {
 	Values []*url.URL
 	Texts  []string

wrap.go

@@ -2,6 +2,23 @@ package flagvar
 
 import "flag"
 
+// WrapPointer wraps a pointer to a `flag.Value`
+// This can be used to switch between different argument parsers.
+type WrapPointer struct {
+	Value *flag.Value
+}
+
+// Set is flag.Value.Set
+func (fv *WrapPointer) Set(v string) error {
+	return (*fv.Value).Set(v)
+}
+
+func (fv WrapPointer) String() string {
+	return (*fv.Value).String()
+}
+
+// WrapFunc wraps a nullary function returning a `flag.Value`
+// This can be used to switch between different argument parsers.
 type WrapFunc func() flag.Value
 
 // Set is flag.Value.Set
@@ -13,6 +30,7 @@ func (fv WrapFunc) String() string {
 	return fv().String()
 }
 
+// Wrap wraps a `flag.Value` and calls `Updated` each time the underlying value is set.
 type Wrap struct {
 	Value   flag.Value
 	Updated func()