fixup Job and Scheduler interface docs

example_test.go

@@ -148,7 +148,7 @@ func ExampleDurationRandomJob() {
 	)
 }
 
-func ExampleJob_ID() {
+func ExampleJob_id() {
 	s, _ := NewScheduler()
 	defer func() { _ = s.Shutdown() }()
 
@@ -164,7 +164,7 @@ func ExampleJob_ID() {
 	fmt.Println(j.ID())
 }
 
-func ExampleJob_LastRun() {
+func ExampleJob_lastRun() {
 	s, _ := NewScheduler()
 	defer func() { _ = s.Shutdown() }()
 
@@ -180,7 +180,26 @@ func ExampleJob_LastRun() {
 	fmt.Println(j.LastRun())
 }
 
-func ExampleJob_NextRun() {
+func ExampleJob_name() {
+	s, _ := NewScheduler()
+	defer func() { _ = s.Shutdown() }()
+
+	j, _ := s.NewJob(
+		DurationJob(
+			time.Second,
+		),
+		NewTask(
+			func() {},
+		),
+		WithName("foobar"),
+	)
+
+	fmt.Println(j.Name())
+	// Output:
+	// foobar
+}
+
+func ExampleJob_nextRun() {
 	s, _ := NewScheduler()
 	defer func() { _ = s.Shutdown() }()
 
@@ -196,7 +215,7 @@ func ExampleJob_NextRun() {
 	fmt.Println(j.NextRun())
 }
 
-func ExampleJob_RunNow() {
+func ExampleJob_runNow() {
 	s, _ := NewScheduler()
 	defer func() { _ = s.Shutdown() }()
 
@@ -218,6 +237,25 @@ func ExampleJob_RunNow() {
 	_ = j.RunNow()
 }
 
+func ExampleJob_tags() {
+	s, _ := NewScheduler()
+	defer func() { _ = s.Shutdown() }()
+
+	j, _ := s.NewJob(
+		DurationJob(
+			time.Second,
+		),
+		NewTask(
+			func() {},
+		),
+		WithTags("foo", "bar"),
+	)
+
+	fmt.Println(j.Tags())
+	// Output:
+	// [foo bar]
+}
+
 func ExampleMonthlyJob() {
 	s, _ := NewScheduler()
 	defer func() { _ = s.Shutdown() }()
@@ -270,7 +308,24 @@ func ExampleOneTimeJob() {
 	s.Start()
 }
 
-func ExampleScheduler_NewJob() {
+func ExampleScheduler_jobs() {
+	s, _ := NewScheduler()
+	defer func() { _ = s.Shutdown() }()
+
+	_, _ = s.NewJob(
+		DurationJob(
+			10*time.Second,
+		),
+		NewTask(
+			func() {},
+		),
+	)
+	fmt.Println(len(s.Jobs()))
+	// Output:
+	// 1
+}
+
+func ExampleScheduler_newJob() {
 	s, _ := NewScheduler()
 	defer func() { _ = s.Shutdown() }()
 
@@ -288,7 +343,7 @@ func ExampleScheduler_NewJob() {
 	fmt.Println(j.ID())
 }
 
-func ExampleScheduler_RemoveByTags() {
+func ExampleScheduler_removeByTags() {
 	s, _ := NewScheduler()
 	defer func() { _ = s.Shutdown() }()
 
@@ -322,7 +377,7 @@ func ExampleScheduler_RemoveByTags() {
 	// 0
 }
 
-func ExampleScheduler_RemoveJob() {
+func ExampleScheduler_removeJob() {
 	s, _ := NewScheduler()
 	defer func() { _ = s.Shutdown() }()
 
@@ -346,7 +401,7 @@ func ExampleScheduler_RemoveJob() {
 	// 0
 }
 
-func ExampleScheduler_Start() {
+func ExampleScheduler_start() {
 	s, _ := NewScheduler()
 	defer func() { _ = s.Shutdown() }()
 
@@ -363,7 +418,7 @@ func ExampleScheduler_Start() {
 	s.Start()
 }
 
-func ExampleScheduler_StopJobs() {
+func ExampleScheduler_stopJobs() {
 	s, _ := NewScheduler()
 	defer func() { _ = s.Shutdown() }()
 
@@ -382,7 +437,12 @@ func ExampleScheduler_StopJobs() {
 	_ = s.StopJobs()
 }
 
-func ExampleScheduler_Update() {
+func ExampleScheduler_shutdown() {
+	s, _ := NewScheduler()
+	defer func() { _ = s.Shutdown() }()
+}
+
+func ExampleScheduler_update() {
 	s, _ := NewScheduler()
 	defer func() { _ = s.Shutdown() }()
 

job.go

@@ -831,12 +831,20 @@ func (o oneTimeJob) next(_ time.Time) time.Time {
 // Job provides the available methods on the job
 // available to the caller.
 type Job interface {
+	// ID returns the job's unique identifier.
 	ID() uuid.UUID
+	// LastRun returns the time of the job's last run
 	LastRun() (time.Time, error)
+	// Name returns the name defined on the job.
 	Name() string
+	// NextRun returns the time of the job's next scheduled run.
 	NextRun() (time.Time, error)
-	Tags() []string
+	// RunNow runs the job once, now. This does not alter
+	// the existing run schedule, and will respect all job
+	// and scheduler limits.
 	RunNow() error
+	// Tags returns the job's string tags.
+	Tags() []string
 }
 
 var _ Job = (*job)(nil)
@@ -853,12 +861,10 @@ type job struct {
 	runJobRequest chan runJobRequest
 }
 
-// ID returns the job's unique identifier.
 func (j job) ID() uuid.UUID {
 	return j.id
 }
 
-// LastRun returns the time of the job's last run
 func (j job) LastRun() (time.Time, error) {
 	ij := requestJob(j.id, j.jobOutRequest)
 	if ij == nil || ij.id == uuid.Nil {
@@ -867,12 +873,10 @@ func (j job) LastRun() (time.Time, error) {
 	return ij.lastRun, nil
 }
 
-// Name returns the name defined on the job.
 func (j job) Name() string {
 	return j.name
 }
 
-// NextRun returns the time of the job's next scheduled run.
 func (j job) NextRun() (time.Time, error) {
 	ij := requestJob(j.id, j.jobOutRequest)
 	if ij == nil || ij.id == uuid.Nil {
@@ -881,14 +885,10 @@ func (j job) NextRun() (time.Time, error) {
 	return ij.nextRun, nil
 }
 
-// Tags returns the job's string tags.
 func (j job) Tags() []string {
 	return j.tags
 }
 
-// RunNow runs the job once, now. This does not alter
-// the existing run schedule, and will respect all job
-// and scheduler limits.
 func (j job) RunNow() error {
 	ctx, cancel := context.WithTimeout(context.Background(), time.Second)
 	defer cancel()

scheduler.go

@@ -16,14 +16,22 @@ var _ Scheduler = (*scheduler)(nil)
 
 // Scheduler defines the interface for the Scheduler.
 type Scheduler interface {
-	// Jobs returns a list of all jobs in the scheduler.
+	// Jobs returns all the jobs currently in the scheduler.
 	Jobs() []Job
-	// NewJob creates a new Job and adds it to the Scheduler.
+	// NewJob creates a new job in the Scheduler. The job is scheduled per the provided
+	// definition when the Scheduler is started. If the Scheduler is already running
+	// the job will be scheduled when the Scheduler is started.
 	NewJob(JobDefinition, Task, ...JobOption) (Job, error)
-	// RemoveByTags removes all jobs matching the provided tags.
+	// RemoveByTags removes all jobs that have at least one of the provided tags.
 	RemoveByTags(...string)
 	// RemoveJob removes the job with the provided id.
 	RemoveJob(uuid.UUID) error
+	// Shutdown should be called when you no longer need
+	// the Scheduler or Job's as the Scheduler cannot
+	// be restarted after calling Shutdown. This is similar
+	// to a Close or Cleanup method and is often deferred after
+	// starting the scheduler.
+	Shutdown() error
 	// Start begins scheduling jobs for execution based
 	// on each job's definition. Job's added to an already
 	// running scheduler will be scheduled immediately based
@@ -33,12 +41,6 @@ type Scheduler interface {
 	// This can be useful in situations where jobs need to be
 	// paused globally and then restarted with Start().
 	StopJobs() error
-	// Shutdown should be called when you no longer need
-	// the Scheduler or Job's as the Scheduler cannot
-	// be restarted after calling Shutdown. This is similar
-	// to a Close or Cleanup method and is often deferred after
-	// starting the scheduler.
-	Shutdown() error
 	// Update replaces the existing Job's JobDefinition with the provided
 	// JobDefinition. The Job's Job.ID() remains the same.
 	Update(uuid.UUID, JobDefinition, Task, ...JobOption) (Job, error)