Comment cleanup

core_flags.go

@@ -14,7 +14,7 @@ import (
 )
 
 // CoreFlags is the default implementation of a [Flags]. It's broadly similar to
-// a [flag.FlagSet], but with additional capabilities inspired by getopt(3).
+// a flag.FlagSet, but with additional capabilities inspired by getopt(3).
 type CoreFlags struct {
 	setName       string
 	flagSlice     []*coreFlag
@@ -40,7 +40,7 @@ func NewFlags(name string) *CoreFlags {
 }
 
 // NewStdFlags returns a core flag set which acts as an adapter for the provided
-// [flag.FlagSet], allowing it to implement the [Flags] interface.
+// flag.FlagSet, allowing it to implement the [Flags] interface.
 //
 // The returned core flag set has slightly different behavior than normal. It's
 // a fixed "snapshot" of the provided stdfs, which means it doesn't allow new

doc.go

@@ -1,14 +1,15 @@
 // Package ff provides a flags-first approach to runtime configuration.
 //
-// The central function is [Parse], which mirrors [flag.FlagSet.Parse],
-// populating a flag set from commandline arguments, environment variables,
-// and/or a config file. [Option] values control parsing behavior.
+// The core function is [Parse], which mirrors the Parse method of a standard
+// flag.FlagSet, populating a flag set from commandline arguments, environment
+// variables, and/or a config file. [Option] values control parsing behavior.
 //
-// [NewFlags] provides a standard flag set, inspired by getopts(3). You can also
-// parse a [flag.FlagSet] directly, or provide your own implementation of the
-// [Flags] interface altogether.
+// [CoreFlags] is provided as a default flag set implementation, inspired by
+// getopts(3). A standard flag.FlagSet can be adapted to a core flag set via
+// [NewStdFlags]. Callers are also free to use their own implementation of the
+// [Flags] interface.
 //
-// [Command] is also provided as a tool for building CLI applications, like
-// docker or kubectl, in a simple and declarative style. It's intended to be
-// easier to understand and maintain than common alternatives.
+// [Command] is provided as a tool for building CLI applications, like docker or
+// kubectl, in a simple and declarative style. It's intended to be easier to
+// understand and maintain than common alternatives.
 package ff

fftest/testcase.go

@@ -8,7 +8,7 @@ import (
 )
 
 // TestCases are a collection of test cases that can be run as a group.
-type TestCases []TestCase
+type TestCases []ParseTest
 
 // Run the test cases in order.
 func (tcs TestCases) Run(t *testing.T, options ...ff.Option) {
@@ -21,8 +21,8 @@ func (tcs TestCases) Run(t *testing.T, options ...ff.Option) {
 	}
 }
 
-// TestCase describes a specific [ff.Parse] test scenario.
-type TestCase struct {
+// ParseTest describes a parsing test scenario.
+type ParseTest struct {
 	Name         string
 	Constructors []Constructor
 	Default      Vars
@@ -34,7 +34,7 @@ type TestCase struct {
 }
 
 // Run the test case.
-func (tc *TestCase) Run(t *testing.T, options ...ff.Option) {
+func (tc *ParseTest) Run(t *testing.T, options ...ff.Option) {
 	t.Helper()
 
 	// The test case options are the most specific, and so the highest priority.

ffval/collections.go

@@ -396,7 +396,7 @@ func (v *Enum[T]) initialize() {
 }
 
 // Set parses the given string, and sets the enum to the successfully parsed
-// value. If the value isn't valid, set fails withg ErrInvalidValue.
+// value. If the value isn't valid, set fails with ErrInvalidValue.
 func (v *Enum[T]) Set(s string) error {
 	v.initialize()
 

ffval/doc.go

@@ -1,11 +1,8 @@
 // Package ffval provides common flag value types and helpers.
 //
-// The types defined by this package implement [flag.Value], and are intended to
-// be used as values in a core flag config.
-//
 // [Value] represents a single instance of any type T that can be parsed from a
-// string. The package defines a set of values for common underlying types, like
-// [Bool], [String], [Duration], etc.
+// string. The package defines a set of values for common types, like [Bool],
+// [String], [Duration], etc.
 //
 // [List] and [UniqueList] represent a sequence of values of type T, where each
 // call to set adds a value to the end of the list. [Enum] represents one of a

options.go

@@ -111,10 +111,9 @@ func WithEnvVarPrefix(prefix string) Option {
 // given delimiter, and to set the flag multiple times, once for each delimited
 // token. Values produced in this way are not trimmed of whitespace.
 //
-// For example, `FOO=a,b,c` might cause a flag named `foo` to receive a single
-// call to Set with the value `a,b,c`. If WithEnvVarSplit is provided as an
-// option, with a delimiter of `,`, then that flag would receive three separate
-// calls to Set with the strings `a`, `b`, and `c`.
+// For example, the env var `FOO=a,b,c` would by default set a flag named `foo`
+// one time, with the value `a,b,c`. Providing WithEnvVarSplit with a comma
+// delimiter would set `foo` multiple times, with the values `a`, `b`, and `c`.
 //
 // By default, no splitting of environment variable values occurs.
 func WithEnvVarSplit(delimiter string) Option {