Added .golangci.yml, updated docstrings

Added golangci-lint configuration

Added some missing docstrings

Removed some commented-out code

Cleaned up tests, made the longer ones parallel

.golangci.yml

@@ -0,0 +1,203 @@
+linters-settings:
+  depguard:
+    rules:
+      logger:
+        deny:
+          # logging is allowed only by logutils.Log,
+          - pkg: "github.com/sirupsen/logrus"
+            desc: logging is allowed only by logutils.Log.
+          - pkg: "github.com/pkg/errors"
+            desc: Should be replaced by standard lib errors package.
+          - pkg: "github.com/instana/testify"
+            desc: It's a fork of github.com/stretchr/testify.
+        files:
+          # logrus is allowed to use only in logutils package.
+          - "!**/pkg/logutils/**.go"
+  dupl:
+    threshold: 100
+  funlen:
+    lines: -1 # the number of lines (code + empty lines) is not a right metric and leads to code without empty line or one-liner.
+    statements: 50
+  goconst:
+    min-len: 2
+    min-occurrences: 3
+  gocritic:
+    enabled-tags:
+      - diagnostic
+      - experimental
+      - opinionated
+      - performance
+      - style
+    disabled-checks:
+      - dupImport # https://github.com/go-critic/go-critic/issues/845
+      #      - ifElseChain
+      - octalLiteral
+      - whyNoLint
+      - hugeParam
+      - rangeValCopy
+  gocyclo:
+    min-complexity: 15
+  godox:
+    keywords:
+      - FIXME
+  gofmt:
+    rewrite-rules:
+      - pattern: 'interface{}'
+        replacement: 'any'
+  goimports:
+    local-prefixes: github.com/golangci/golangci-lint
+  mnd:
+    # don't include the "operation" and "assign"
+    checks:
+      - argument
+      - case
+      - condition
+      - return
+    ignored-numbers:
+      - '0'
+      - '1'
+      - '2'
+      - '3'
+    ignored-functions:
+      - strings.SplitN
+  govet:
+    settings:
+      printf:
+        funcs:
+          - (github.com/golangci/golangci-lint/pkg/logutils.Log).Infof
+          - (github.com/golangci/golangci-lint/pkg/logutils.Log).Warnf
+          - (github.com/golangci/golangci-lint/pkg/logutils.Log).Errorf
+          - (github.com/golangci/golangci-lint/pkg/logutils.Log).Fatalf
+    enable:
+      - nilness
+      - shadow
+    disable:
+      - loopclosure
+  errorlint:
+    asserts: false
+  lll:
+    line-length: 100
+  misspell:
+    locale: US
+    ignore-words:
+      - "importas" # linter name
+  nolintlint:
+    allow-unused: false # report any unused nolint directives
+    require-explanation: true # require an explanation for nolint directives
+    require-specific: true # require nolint directives to be specific about which linter is being skipped
+  revive:
+    rules:
+      - name: indent-error-flow
+      - name: unexported-return
+        disabled: true
+      - name: unused-parameter
+      - name: unused-receiver
+
+linters:
+  disable-all: true
+  enable:
+    - bodyclose
+    - depguard
+    - dogsled
+    - dupl
+    - errcheck
+    - errorlint
+    - exportloopref
+    - funlen
+    - gocheckcompilerdirectives
+    - gochecknoinits
+    - goconst
+    - gocritic
+    - gocyclo
+    - godox
+    - gofmt
+    - goimports
+    #    - mnd
+    - goprintffuncname
+    - gosec
+    - gosimple
+    - govet
+    - ineffassign
+    - lll
+    #    - misspell
+    - nakedret
+    - noctx
+    - nolintlint
+    - revive
+    - staticcheck
+    - stylecheck
+    - testifylint
+    - unconvert
+    - unparam
+    - unused
+    - whitespace
+
+  # This list of linters is not a recommendation (same thing for all this configuration file).
+  # We intentionally use a limited set of linters.
+  # See the comment on top of this file.
+
+issues:
+  exclude-rules:
+    - path: (.+)_test\.go
+      linters:
+        - dupl
+        - mnd
+        - lll
+
+    # The logic of creating a linter is similar between linters, it's not duplication.
+    - path: pkg/golinters
+      linters:
+        - dupl
+
+    # Deprecated configuration options.
+    - path: pkg/commands/run.go
+      linters: [staticcheck]
+      text: "SA1019: c.cfg.Run.ShowStats is deprecated: use Output.ShowStats instead."
+
+    # Deprecated linter options.
+    - path: pkg/golinters/errcheck/errcheck.go
+      linters: [staticcheck]
+      text: "SA1019: errCfg.Exclude is deprecated: use ExcludeFunctions instead"
+    - path: pkg/golinters/errcheck/errcheck.go
+      linters: [staticcheck]
+      text: "SA1019: errCfg.Ignore is deprecated: use ExcludeFunctions instead"
+    - path: pkg/golinters/govet/govet.go
+      linters: [staticcheck]
+      text: "SA1019: cfg.CheckShadowing is deprecated: the linter should be enabled inside Enable."
+    - path: pkg/golinters/godot/godot.go
+      linters: [staticcheck]
+      text: "SA1019: settings.CheckAll is deprecated: use Scope instead"
+    - path: pkg/golinters/gci/gci.go
+      linters: [staticcheck]
+      text: "SA1019: settings.LocalPrefixes is deprecated: use Sections instead."
+    - path: pkg/golinters/mnd/mnd.go
+      linters: [staticcheck]
+      text: "SA1019: settings.Settings is deprecated: use root level settings instead."
+    - path: pkg/golinters/mnd/mnd.go
+      linters: [staticcheck]
+      text: "SA1019: config.GoMndSettings is deprecated: use MndSettings."
+
+    # Related to `run.go`, it cannot be removed.
+    - path: pkg/golinters/gofumpt/gofumpt.go
+      linters: [staticcheck]
+      text: "SA1019: settings.LangVersion is deprecated: use the global `run.go` instead."
+    - path: pkg/golinters/internal/staticcheck_common.go
+      linters: [staticcheck]
+      text: "SA1019: settings.GoVersion is deprecated: use the global `run.go` instead."
+    - path: pkg/lint/lintersdb/manager.go
+      linters: [staticcheck]
+      text: "SA1019: (.+).(GoVersion|LangVersion) is deprecated: use the global `run.go` instead."
+
+    # Based on existing code, the modifications should be limited to make maintenance easier.
+    - path: pkg/golinters/unused/unused.go
+      linters: [gocritic]
+      text: "rangeValCopy: each iteration copies 160 bytes \\(consider pointers or indexing\\)"
+
+  exclude-dirs:
+    - test/testdata_etc # test files
+    - internal/cache # extracted from Go code
+    - internal/renameio # extracted from Go code
+    - internal/robustio # extracted from Go code
+
+run:
+  timeout: 5m

job.go

@@ -115,13 +115,43 @@ func (s ScheduledJob) LogValue() slog.Value {
 	)
 }
 
+// ScheduleFunc creates and starts a new ScheduledJob with the given schedule and options.
+// It immediately begins executing the provided function according to the schedule.
+//
+// The function f will be called with the current time whenever the schedule is triggered.
+// If f returns an error, it will be recorded in the job's runtime history.
+//
+// Parameters:
+//   - ctx: A context.Context for cancellation and timeout control.
+//   - schedule: A *Schedule that determines when the job should run.
+//   - opts: ScheduledJobOptions to configure the job's behavior.
+//   - f: A function to be executed on each scheduled tick, with the signature func(time.Time) error.
+//
+// Returns:
+//   - *ScheduledJob: A pointer to the newly created and started ScheduledJob.
+//
+// The returned ScheduledJob is already running and does not need to be started manually.
+// Use the returned ScheduledJob's methods (e.g., Stop, Suspend, Resume) to control its execution.
+//
+// Example:
+//
+//	schedule, _ := crong.New("*/5 * * * *", nil)
+//	job := crong.ScheduleFunc(ctx, schedule, crong.ScheduledJobOptions{
+//		MaxConcurrent: 1,
+//		TickerReceiveTimeout: 5 * time.Second,
+//	}, func(t time.Time) error {
+//		fmt.Printf("Job ran at %v\n", t)
+//		return nil
+//	})
+//
+//	// ... later
+//	job.Stop(context.Background())
 func ScheduleFunc(
 	ctx context.Context,
 	schedule *Schedule,
 	opts ScheduledJobOptions,
 	f func(t time.Time) error,
 ) *ScheduledJob {
-
 	s := &ScheduledJob{
 		schedule:          schedule,
 		ticker:            NewTicker(ctx, schedule, opts.TickerReceiveTimeout),

job_test.go

@@ -10,7 +10,7 @@ import (
 
 func TestScheduledJob(t *testing.T) {
 	ctx, cancel := context.WithTimeout(context.Background(), 120*time.Second)
-	defer cancel()
+	t.Cleanup(cancel)
 
 	s, err := New("* * * * *", nil) // every minute
 	if err != nil {
@@ -32,14 +32,6 @@ func TestScheduledJob(t *testing.T) {
 			return nil
 		},
 	)
-	go func() {
-		select {
-		case <-ctx.Done():
-			if errors.Is(ctx.Err(), context.DeadlineExceeded) {
-				t.Fatalf("expected results")
-			}
-		}
-	}()
 
 	// push some ticks instead of waiting 60 seconds
 	sf.ticker.tick(ctx)

schedule_test.go

@@ -640,15 +640,6 @@ func checkTimes(t *testing.T, tc testCase, s *Schedule) {
 		)
 	}
 
-	// currentSchedule := testCases[0]
-	// if !s.Matches(currentSchedule) {
-	// 	t.Fatalf(
-	// 		"expected %s to match %s",
-	// 		currentSchedule,
-	// 		s.String(),
-	// 	)
-	// }
-
 	for i := 0; i < len(testCases); i++ {
 		if i+1 == len(testCases) {
 			break

ticker.go

@@ -9,6 +9,7 @@ import (
 	"time"
 )
 
+// Logger used by [Ticker] and [ScheduledJob]. By default, it discards all logs.
 var Logger = slog.New(slog.NewTextHandler(io.Discard, nil))
 
 // Ticker is a cron ticker that sends the current time

ticker_test.go

@@ -7,6 +7,8 @@ import (
 )
 
 func TestTicker(t *testing.T) {
+	t.Parallel()
+
 	ctx, cancel := context.WithTimeout(context.Background(), 120*time.Second)
 	defer cancel()
 
@@ -65,9 +67,11 @@ func TestEarlyTicker(t *testing.T) {
 	}
 }
 
+// TestTickerCanceled verifies that we no longer receive ticks after
+// canceling the context provided to the ticker
 func TestTickerCanceled(t *testing.T) {
-	// verify that we no longer receive ticks after canceling
-	// the tick context
+	t.Parallel()
+
 	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
 	defer cancel()
 
@@ -116,6 +120,8 @@ func TestTickerCanceled(t *testing.T) {
 }
 
 func TestTickerSendTimeout(t *testing.T) {
+	t.Parallel()
+
 	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
 	defer cancel()