docs: add fname package comments

Author: Splode

dictionary.go

@@ -1,3 +1,4 @@
+// package fname contains functions for generating random, human-friendly names.
 package fname
 
 import (
@@ -16,13 +17,15 @@ const (
 //go:embed data/*
 var dataFS embed.FS
 
+// Dictionary is a collection of words.
 type Dictionary struct {
 	adectives []string
 	adverbs   []string
 	nouns     []string
 	verbs     []string
 }
 
+// NewDictionary creates a new dictionary.
 func NewDictionary() *Dictionary {
 	// TODO: allow for custom dictionary
 	a, err := loadFile(adjectiveFilePath)
@@ -50,50 +53,59 @@ func NewDictionary() *Dictionary {
 	}
 }
 
+// Adjective returns a random adjective.
 func (d *Dictionary) Adjective(idx int) (string, error) {
 	if idx < 0 || idx >= len(d.adectives) {
 		return "", fmt.Errorf("index out of range: %d", idx)
 	}
 	return d.adectives[idx], nil
 }
 
+// Adverb returns a random adverb.
 func (d *Dictionary) Adverb(idx int) (string, error) {
 	if idx < 0 || idx >= len(d.adverbs) {
 		return "", fmt.Errorf("index out of range: %d", idx)
 	}
 	return d.adverbs[idx], nil
 }
 
+// Noun returns a random noun.
 func (d *Dictionary) Noun(idx int) (string, error) {
 	if idx < 0 || idx >= len(d.nouns) {
 		return "", fmt.Errorf("index out of range: %d", idx)
 	}
 	return d.nouns[idx], nil
 }
 
+// Verb returns a random verb.
 func (d *Dictionary) Verb(idx int) (string, error) {
 	if idx < 0 || idx >= len(d.verbs) {
 		return "", fmt.Errorf("index out of range: %d", idx)
 	}
 	return d.verbs[idx], nil
 }
 
+// LengthAdjective returns the number of adjectives in the dictionary.
 func (d *Dictionary) LengthAdjective() int {
 	return len(d.adectives)
 }
 
+// LengthAdverb returns the number of adverbs in the dictionary.
 func (d *Dictionary) LengthAdverb() int {
 	return len(d.adverbs)
 }
 
+// LengthNoun returns the number of nouns in the dictionary.
 func (d *Dictionary) LengthNoun() int {
 	return len(d.nouns)
 }
 
+// LengthVerb returns the number of verbs in the dictionary.
 func (d *Dictionary) LengthVerb() int {
 	return len(d.verbs)
 }
 
+// loadFile loads a file from the embedded filesystem, and returns a slice of strings containing each line.
 func loadFile(path string) ([]string, error) {
 	f, err := dataFS.Open(path)
 	if err != nil {

generator.go

@@ -1,3 +1,4 @@
+// package fname contains functions for generating random, human-friendly names.
 package fname
 
 import (
@@ -7,33 +8,39 @@ import (
 	"time"
 )
 
+// Generator is a random name generator.
 type Generator struct {
 	dict      *Dictionary
 	delimiter string
 	seed      int64
 	size      uint
 }
 
+// GeneratorOption is a function that configures a Generator.
 type GeneratorOption func(*Generator)
 
+// WithDelimiter sets the delimiter used to join words.
 func WithDelimiter(delimiter string) GeneratorOption {
 	return func(r *Generator) {
 		r.delimiter = delimiter
 	}
 }
 
+// WithSeed sets the seed used to generate random numbers.
 func WithSeed(seed int64) GeneratorOption {
 	return func(r *Generator) {
 		r.seed = seed
 	}
 }
 
+// WithSize sets the number of words in the generated name.
 func WithSize(size uint) GeneratorOption {
 	return func(r *Generator) {
 		r.size = size
 	}
 }
 
+// NewGenerator creates a new Generator.
 func NewGenerator(opts ...GeneratorOption) *Generator {
 	r := &Generator{
 		dict:      NewDictionary(),
@@ -48,6 +55,7 @@ func NewGenerator(opts ...GeneratorOption) *Generator {
 	return r
 }
 
+// Generate generates a random name.
 func (r *Generator) Generate() (string, error) {
 	// TODO: address case where adjective and noun are the same, such as "orange-orange" or "sound-sound"
 	adjective, err := r.dict.Adjective(rand.Intn(r.dict.LengthAdjective()))