From c5a9f0916656d57adadc1d19dd8585da0fa7d656 Mon Sep 17 00:00:00 2001 From: Dan Jones Date: Mon, 31 Mar 2025 12:10:05 -0500 Subject: [PATCH] =?UTF-8?q?=F0=9F=92=A1=20Improve=20go=20doc=20comments=20?= =?UTF-8?q?with=20internal=20links?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- config.go | 7 +++++-- gen_file.go | 12 ++++++------ gen_int.go | 8 ++++---- gen_rand.go | 12 ++++++------ gen_ts.go | 10 +++++----- generators.go | 12 ++++++------ nomino.go | 5 +++-- options.go | 6 +++--- 8 files changed, 38 insertions(+), 34 deletions(-) diff --git a/config.go b/config.go index c889a06..0c06449 100644 --- a/config.go +++ b/config.go @@ -1,5 +1,6 @@ package nomino +// Config controls how the generatred filename is created. type Config struct { original string prefix string @@ -9,7 +10,9 @@ type Config struct { generator Generator } -// NewConfig returns a new Config with the specified Options. +// NewConfig returns a new [Config] with the specified [Option]s. +// With no Options, the Config uses an extension of .txt, a separator +// of _, and the [UUID] [Generator]. func NewConfig(options ...Option) Config { conf := Config{ extension: ".txt", @@ -22,7 +25,7 @@ func NewConfig(options ...Option) Config { return conf } -// AddOptions creates a new Config with options added. +// AddOptions creates a new [Config] with the given [Option]s added. func (c Config) AddOptions(options ...Option) Config { for _, opt := range options { opt(&c) diff --git a/gen_file.go b/gen_file.go index b602557..c701f11 100644 --- a/gen_file.go +++ b/gen_file.go @@ -9,7 +9,7 @@ import ( "github.com/gosimple/slug" ) -// ErrMissingOriginal is the error returned by Slug if there is no filename. +// ErrMissingOriginal is the error returned by [Slug] if there is no filename. var ErrMissingOriginal = errors.New("missing original filename") func getOriginal(c *Config) (string, error) { @@ -37,21 +37,21 @@ func Slug(lang ...string) Generator { } } -// HashingFunc is a function that generates a hash.Hash. +// HashingFunc is a function that generates a [hash.Hash]. type HashingFunc func() hash.Hash -// New allows HashingFunc to be used as a Hasher. +// New allows [HashingFunc] to be used as a [Hasher]. func (hf HashingFunc) New() hash.Hash { return hf() } -// Hasher is a type returns a hash.Hash. -// All crypto.Hash may be used. +// Hasher is a type returns a [hash.Hash]. +// All [crypto.Hash] may be used. type Hasher interface { New() hash.Hash } -// ErrInvalidHash is returned by the Hash generator when an invalid HashType is passed. +// ErrInvalidHash is returned by the [Hash] [Generator] when an invalid [Hasher] is passed. var ErrInvalidHash = errors.New("invalid hash type") // Hash generates a name from a hash of the filename. diff --git a/gen_int.go b/gen_int.go index 3174d18..bb57261 100644 --- a/gen_int.go +++ b/gen_int.go @@ -11,7 +11,7 @@ type incConf struct { cb func(int) string } -// IncrementalOption sets an option for the Incremental Generator. +// IncrementalOption sets an option for the [Incremental] [Generator]. type IncrementalOption func(c *incConf) // Incremental generates a name that is a series of integers. @@ -30,21 +30,21 @@ func Incremental(opts ...IncrementalOption) Generator { } } -// IncrementalStart sets the starting integer for Incremental. +// IncrementalStart sets the starting integer for [Incremental]. func IncrementalStart(start int) IncrementalOption { return func(c *incConf) { c.start = start } } -// IncrementalStepsets the step by which Incremental increases with each invocation. +// IncrementalStepsets the step by which [Incremental] increases with each invocation. func IncrementalStep(step int) IncrementalOption { return func(c *incConf) { c.step = step } } -// IncrementalFormatsets the format for the number generated by Incremental. +// IncrementalFormatsets the format for the number generated by [Incremental]. // It will be formatted with Printf. This is mostly likely useful with a format like "%02d". func IncrementalFormat(format string) IncrementalOption { return func(c *incConf) { diff --git a/gen_rand.go b/gen_rand.go index bdabef6..7a9e9ea 100644 --- a/gen_rand.go +++ b/gen_rand.go @@ -9,7 +9,7 @@ import ( ) // UUIDer is an interface for generating UUIDs. -// It is recommended that you use either the UUIDv4 or UUIDv7 variables. +// It is recommended that you use either the [UUIDv4] or [UUIDv7] variables. type UUIDer interface { UUID() (uuid.UUID, error) } @@ -17,7 +17,7 @@ type UUIDer interface { // UUIDFunc is a function that generates a UUID. type UUIDFunc func() (uuid.UUID, error) -// UUID allows UUIDFunc to be used as a UUIDer. +// UUID allows [UUIDFunc] to be used as a [UUIDer]. func (u UUIDFunc) UUID() (uuid.UUID, error) { return u() } @@ -33,7 +33,7 @@ var ( UUIDv7 = UUIDFunc(uuid.NewV7) ) -// UUID generates a UUID. If nil.is passed as an argument, +// UUID generates a UUID. If nil is passed as an argument, // a UUIDv4 is generated. func UUID(u UUIDer) Generator { if u == nil { @@ -52,10 +52,10 @@ type randConf struct { length int } -// RandomOption is an option for the Random Generator. +// RandomOption is an option for the [Random] [Generator]. type RandomOption func(*randConf) -// RandomLength controls the length of the string generated by Random. +// RandomLength controls the length of the string generated by [Random]. func RandomLength(length int) RandomOption { return func(c *randConf) { c.length = length @@ -75,7 +75,7 @@ func fillBuffer(buff *strings.Builder, length int) { } } -// Random generates a random string containing the characters [A-Za-z0-9]. +// Random generates a random string containing the characters A-Za-z0-9. // By default, it will be eight characters long. func Random(opts ...RandomOption) Generator { c := randConf{8} diff --git a/gen_ts.go b/gen_ts.go index 05d6e0c..62fe703 100644 --- a/gen_ts.go +++ b/gen_ts.go @@ -2,10 +2,10 @@ package nomino import "time" -// FileTimestamp is the default format for WithTimestamp and WithTime. +// FileTimestamp is the default format for [Timestamp]. const FileTimestamp string = "2006-01-02T15-04-05-0700" -// FileTimestampNoTZ is the default format for WithTimestampUTC and WithTimeUTC. +// FileTimestampNoTZ is the default format when using the [TimestampUTC] [TimestampOption]. const FileTimestampNoTZ string = "2006-01-02T15-04-05" type timestampConf struct { @@ -14,7 +14,7 @@ type timestampConf struct { utc bool } -// TimestampOption provides options for the Timestamp Generator. +// TimestampOption provides options for the [Timestamp] [Generator]. type TimestampOption func(c *timestampConf) // Timestamp generates a a date and time. By default, it uses the current time, and will. @@ -35,7 +35,7 @@ func Timestamp(opts ...TimestampOption) Generator { } // TimestampFormat sets the format for the generated name. -// Consult time.Time.Format for details on the format. +// Consult [time.Time.Format] for details on the format. func TimestampFormat(format string) TimestampOption { return func(c *timestampConf) { c.format = format @@ -43,7 +43,7 @@ func TimestampFormat(format string) TimestampOption { } // TimestampTime sets the time for the generated name. -// By default, it uses the current time. +// By default, [Timestamp] uses the current time. func TimestampTime(t time.Time) TimestampOption { return func(c *timestampConf) { c.ts = t diff --git a/generators.go b/generators.go index 9e31913..fe7b59d 100644 --- a/generators.go +++ b/generators.go @@ -10,25 +10,25 @@ import ( // for example. type Generator func(conf *Config) (string, error) -// Make allows you to generate a new string directly from a Generator. +// Make allows you to generate a new string directly from a [Generator]. func (g Generator) Make(opts ...Option) (string, error) { return g.MakeWithConfig(NewConfig(opts...)) } -// MakeWithConfig allows you to generate a new string directly from a Generator +// MakeWithConfig allows you to generate a new string directly from a [Generator] // with a pre-existing Config. func (g Generator) MakeWithConfig(c Config) (string, error) { return Make(c.AddOptions(WithGenerator(g))) } -// WithGenerator sets the specified generator. +// WithGenerator sets the specified [Generator]. func WithGenerator(g Generator) Option { return func(c *Config) { c.generator = g } } -// ErrMissingGenerators is returned by a multi-generator if no generators are supplied. +// ErrMissingGenerators is returned by a multi-generator if no [Generator]s are supplied. var ErrMissingGenerators = errors.New("no generators supplied") func missingGen(*Config) (string, error) { @@ -36,7 +36,7 @@ func missingGen(*Config) (string, error) { } // MultiGeneratorInOrder allows the use of multiple generators. Each new invokation will use the next generator in turn. -// If none are passed, the generator will always return ErrMissingGenerators. +// If none are passed, the generator will always return [ErrMissingGenerators]. func MultiGeneratorInOrder(gens ...Generator) Generator { if len(gens) == 0 { return missingGen @@ -55,7 +55,7 @@ func MultiGeneratorInOrder(gens ...Generator) Generator { } // MultiGeneratorRandomOrder allows the use of multiple generators. Each new invokation will use one of the generators randomly. -// If none are passed, the generator will always return ErrMissingGenerators. +// If none are passed, the generator will always return [ErrMissingGenerators]. func MultiGeneratorRandomOrder(gens ...Generator) Generator { if len(gens) == 0 { return missingGen diff --git a/nomino.go b/nomino.go index 8310519..185fcc3 100644 --- a/nomino.go +++ b/nomino.go @@ -1,6 +1,7 @@ // Package nomino is a utility that allows us to generate random filenames. // // There are two main methods of using nomino. -// 1. Using the `nomini.Make` function. -// 2. Creating a generator, and using its `Make` method. +// +// 1. Using the [Make] function. +// 2. Creating a generator, and using its [Generator.Make] method. package nomino diff --git a/options.go b/options.go index 6cc87a8..3550b02 100644 --- a/options.go +++ b/options.go @@ -6,7 +6,7 @@ import ( "github.com/gosimple/slug" ) -// Option sets configuration parameters for Config. +// Option sets configuration parameters for [Config]. type Option func(c *Config) // WithOriginal sets the original filename. @@ -18,7 +18,7 @@ func WithOriginal(o string) Option { } // WithOriginal sets the original filename as a slug. -// This should not be used with the Slug Generator (as it would be redundant). +// This should not be used with the [Slug] [Generator] (as it would be redundant). func WithOriginalSlug(o string) Option { return func(c *Config) { c.original = slug.Make(o) @@ -26,7 +26,7 @@ func WithOriginalSlug(o string) Option { } // WithOriginal sets the original filename as a slug, taking the language into account. -// This should not be used with the Slug Generator (as it would be redundant). +// This should not be used with the [Slug] [Generator] (as it would be redundant). func WithOriginalSlugLang(o, lang string) Option { return func(c *Config) { c.original = slug.MakeLang(o, lang)