Naming, layout and comments: descriptive full-word names, one item per line in wrapped calls and literals, and doc comments on exported names

Short and single-letter names in application code become full words (tests
keep theirs). Wrapped calls, signatures and composite literals put one item
per line, and one-line function bodies are expanded. Exported names and
groups of constants get doc comments, and comments refer to the renamed
identifiers.

internal/fetcher/fetcher.go

@@ -12,6 +12,8 @@ import (
 	"git.avsdev.uk/Go/job-search/internal/util"
 )
 
+// ErrNoNewReleases is returned by a source's task when there was nothing new
+// to fetch; it wraps util.ErrWorkerNoWork.
 var ErrNoNewReleases = fmt.Errorf("%w: no new releases", util.ErrWorkerNoWork)
 
 // Option configures Run.

internal/fetcher/fetcher_test.go

@@ -77,7 +77,9 @@ func TestFetchFunctions(t *testing.T) {
 			"releases found",
 			http.StatusOK,
 			onePackage,
-			func(err error) bool { return err == nil },
+			func(err error) bool {
+				return err == nil
+			},
 			"nil",
 		},
 		{"no releases", http.StatusOK, emptyPackage, func(err error) bool {
@@ -92,7 +94,10 @@ func TestFetchFunctions(t *testing.T) {
 			t.Run(fname+"/"+tc.name, func(t *testing.T) {
 				srv, hits := ftsServer(t, tc.status, tc.body)
 				err := fetch(
-					context.Background(), slog.Default(), confFor(srv.URL), time.Now().Add(-time.Hour),
+					context.Background(),
+					slog.Default(),
+					confFor(srv.URL),
+					time.Now().Add(-time.Hour),
 				)
 				if !tc.check(err) {
 					t.Fatalf("err = %v, want %s", err, tc.wantErr)
@@ -204,7 +209,9 @@ func TestRunLogsSourceErrors(t *testing.T) {
 	var buf bytes.Buffer
 	def := slog.Default()
 	slog.SetDefault(slog.New(slog.NewTextHandler(&buf, nil)))
-	t.Cleanup(func() { slog.SetDefault(def) })
+	t.Cleanup(func() {
+		slog.SetDefault(def)
+	})
 
 	// A zero interval makes each worker fail straight away.
 	conf := &config.JobSearchConfig{}
@@ -253,7 +260,9 @@ func TestRunShutsDownOnWorkerError(t *testing.T) {
 	conf.Sources.Sleeper.Enabled = true
 
 	done := make(chan error, 1)
-	go func() { done <- Run(context.Background(), conf, time.Now().Add(-time.Hour)) }()
+	go func() {
+		done <- Run(context.Background(), conf, time.Now().Add(-time.Hour))
+	}()
 
 	select {
 	case err := <-done:

internal/fetcher/worker_findatender.go

@@ -15,9 +15,12 @@ import (
 // runFindAOpportunity polls Find a Tender every configured interval until ctx
 // is cancelled.
 func runFindAOpportunity(
-	ctx context.Context, logger *slog.Logger, conf *config.JobSearchConfig, since time.Time,
+	ctx context.Context,
+	logger *slog.Logger,
+	conf *config.JobSearchConfig,
+	since time.Time,
 ) error {
-	w := util.Worker{
+	worker := util.Worker{
 		Logger:   logger,
 		Name:     "FindAOpportunity",
 		Interval: conf.Sources.FindATender.Interval,
@@ -25,19 +28,26 @@ func runFindAOpportunity(
 			return fetchFindAOpportunity(ctx, logger, conf, since)
 		},
 	}
-	return w.Run(ctx, since)
+	return worker.Run(ctx, since)
 }
 
 // fetchFindAOpportunity fetches everything updated since since from Find a
 // Tender. Finding nothing returns ErrNoNewReleases, so the worker still moves
 // its checkpoint on.
 func fetchFindAOpportunity(
-	ctx context.Context, logger *slog.Logger, conf *config.JobSearchConfig, since time.Time,
+	ctx context.Context,
+	logger *slog.Logger,
+	conf *config.JobSearchConfig,
+	since time.Time,
 ) error {
 	opportunities, err := util.AwaitTask(ctx, func() ([]*types.Opportunity, error) {
-		ft := findatender.New(conf, conf.Sources.FindATender.APIRoot, findatender.WithLogger(logger))
-		defer ft.Shutdown()
-		return ft.With(ctx).FetchAll(since, true)
+		findATender := findatender.New(
+			conf,
+			conf.Sources.FindATender.APIRoot,
+			findatender.WithLogger(logger),
+		)
+		defer findATender.Shutdown()
+		return findATender.With(ctx).FetchAll(since, true)
 	})
 	if errors.Is(err, findatender.ErrNoReleases) {
 		return ErrNoNewReleases

internal/fetcher/worker_ftsmock.go

@@ -15,9 +15,12 @@ import (
 // runFTSMock polls the mock Find a Tender server every configured interval
 // until ctx is cancelled.
 func runFTSMock(
-	ctx context.Context, logger *slog.Logger, conf *config.JobSearchConfig, since time.Time,
+	ctx context.Context,
+	logger *slog.Logger,
+	conf *config.JobSearchConfig,
+	since time.Time,
 ) error {
-	w := util.Worker{
+	worker := util.Worker{
 		Logger:   logger,
 		Name:     "FTSMock",
 		Interval: conf.Sources.FTSMock.Interval,
@@ -25,19 +28,26 @@ func runFTSMock(
 			return fetchFTSMock(ctx, logger, conf, since)
 		},
 	}
-	return w.Run(ctx, since)
+	return worker.Run(ctx, since)
 }
 
 // fetchFTSMock fetches everything updated since since from the mock Find a
 // Tender server. Finding nothing returns ErrNoNewReleases, so the worker still
 // moves its checkpoint on.
 func fetchFTSMock(
-	ctx context.Context, logger *slog.Logger, conf *config.JobSearchConfig, since time.Time,
+	ctx context.Context,
+	logger *slog.Logger,
+	conf *config.JobSearchConfig,
+	since time.Time,
 ) error {
 	opportunities, err := util.AwaitTask(ctx, func() ([]*types.Opportunity, error) {
-		ft := findatender.New(conf, conf.Sources.FTSMock.APIRoot, findatender.WithLogger(logger))
-		defer ft.Shutdown()
-		return ft.With(ctx).FetchAll(since, true)
+		findATender := findatender.New(
+			conf,
+			conf.Sources.FTSMock.APIRoot,
+			findatender.WithLogger(logger),
+		)
+		defer findATender.Shutdown()
+		return findATender.With(ctx).FetchAll(since, true)
 	})
 	if errors.Is(err, findatender.ErrNoReleases) {
 		return ErrNoNewReleases

internal/fetcher/worker_sleeper.go

@@ -15,10 +15,13 @@ const sleepDuration = 60 * time.Second
 // runSleeper runs the sleeper test source until ctx is cancelled: every
 // configured interval it simulates work by sleeping for sleepDuration.
 func runSleeper(
-	ctx context.Context, logger *slog.Logger, conf *config.JobSearchConfig, since time.Time,
+	ctx context.Context,
+	logger *slog.Logger,
+	conf *config.JobSearchConfig,
+	since time.Time,
 ) error {
 	blockShutdown := conf.Sources.Sleeper.BlockShutdown
-	w := util.Worker{
+	worker := util.Worker{
 		Logger:   logger,
 		Name:     "Sleeper",
 		Interval: conf.Sources.Sleeper.Interval,
@@ -30,7 +33,7 @@ func runSleeper(
 			}
 		},
 	}
-	return w.Run(ctx, since)
+	return worker.Run(ctx, since)
 }
 
 // sleep simulates work taking duration, returning early with ctx.Err() if ctx