From 5b307f56dd52f0b5d16380c97c844a6953ba52be Mon Sep 17 00:00:00 2001
From: Copilot <198982749+Copilot@users.noreply.github.com>
Date: Fri, 20 Mar 2026 11:58:16 -0500
Subject: [PATCH] docs: clarify NextRun/NextRuns require scheduler to be
 started (#910)

* Initial plan

* docs: clarify NextRun and NextRuns return empty values until scheduler is started

Co-authored-by: JohnRoesler <19351306+JohnRoesler@users.noreply.github.com>

* docs: remove unhelpful inline comments from NextRun/NextRuns examples

Co-authored-by: JohnRoesler <19351306+JohnRoesler@users.noreply.github.com>
Agent-Logs-Url: https://github.com/go-co-op/gocron/sessions/9686e808-ae5e-4bc8-ad00-f78a1a7b079d

* docs: restore inline comments for NextRun/NextRuns examples

Co-authored-by: JohnRoesler <19351306+JohnRoesler@users.noreply.github.com>
Agent-Logs-Url: https://github.com/go-co-op/gocron/sessions/df5afb1e-5c66-4615-9967-a2efc2419d87

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: JohnRoesler <19351306+JohnRoesler@users.noreply.github.com>
---
 example_test.go | 6 ++++++
 job.go          | 4 ++++
 2 files changed, 10 insertions(+)

diff --git a/example_test.go b/example_test.go
index 310fb43..3d449d1 100644
--- a/example_test.go
+++ b/example_test.go
@@ -267,6 +267,9 @@ func ExampleJob_nextRun() {
 		),
 	)
 
+	// NextRun is only available after the scheduler has been started.
+	s.Start()
+
 	nextRun, _ := j.NextRun()
 	fmt.Println(nextRun)
 }
@@ -284,6 +287,9 @@ func ExampleJob_nextRuns() {
 		),
 	)
 
+	// NextRuns is only available after the scheduler has been started.
+	s.Start()
+
 	nextRuns, _ := j.NextRuns(5)
 	fmt.Println(nextRuns)
 }
diff --git a/job.go b/job.go
index 67930e2..cd0f4e1 100644
--- a/job.go
+++ b/job.go
@@ -1190,8 +1190,12 @@ type Job interface {
 	// Name returns the name defined on the job.
 	Name() string
 	// NextRun returns the time of the job's next scheduled run.
+	// This value is only available once the scheduler has been started
+	// with Scheduler.Start(). Before that, it returns the zero time value.
 	NextRun() (time.Time, error)
 	// NextRuns returns the requested number of calculated next run values.
+	// These values are only available once the scheduler has been started
+	// with Scheduler.Start(). Before that, it returns nil.
 	NextRuns(int) ([]time.Time, error)
 	// RunNow runs the job once, now. This does not alter
 	// the existing run schedule, and will respect all job