docs: update readme documentation (#154)

README.md

@@ -12,6 +12,14 @@ A minimalistic and zero-dependency scheduling library for Go.
 The implementation is inspired by the design of the [Quartz](https://github.com/quartz-scheduler/quartz)
 Java scheduler.
 
+The core [scheduler](#scheduler-interface) component can be used to manage scheduled [jobs](#job-interface) (tasks)
+using [triggers](#trigger-interface).
+The implementation of the cron trigger fully supports the Quartz [cron expression format](#cron-expression-format)
+and can be used independently to calculate a future time given the previous execution time.
+
+If you need to run multiple instances of the scheduler, see the [distributed mode](#distributed-mode) section for
+guidance.
+
 ### Library building blocks
 
 #### Scheduler interface
@@ -113,35 +121,61 @@ Several common Job implementations can be found in the [job](./job) package.
 | Day of week  | YES       | 1-7 or SUN-SAT  | , - * ? / L #              |
 | Year         | NO        | empty, 1970-    | , - * /                    |
 
+### Special characters
+
+- `*`: All values in a field (e.g., `*` in minutes = "every minute").
+- `?`: No specific value; use when specifying one of two related fields (e.g., "10" in day-of- month, `?` in
+  day-of-week).
+- `-`: Range of values (e.g., `10-12` in hour = "hours 10, 11, and 12").
+- `,`: List of values (e.g., `MON,WED,FRI` in day-of-week = "Monday, Wednesday, Friday").
+- `/`: Increments (e.g., `0/15` in seconds = "0, 15, 30, 45"; `1/3` in day-of-month = "every 3 days from the 1st").
+- `L`: Last day; meaning varies by field. Ranges or lists are not allowed with `L`.
+  - Day-of-month: Last day of the month (e.g, `L-3` is the third to last day of the month).
+  - Day-of-week: Last day of the week (7 or SAT) when alone; "last xxx day" when used after
+    another value (e.g., `6L` = "last Friday").
+- `W`: Nearest weekday in the month to the given day (e.g., `15W` = "nearest weekday to the 15th"). If `1W` on
+  Saturday, it fires Monday the 3rd. `W` only applies to a single day, not ranges or lists.
+- `#`: Nth weekday of the month (e.g., `6#3` = "third Friday"; `2#1` = "first Monday"). Firing does not occur if
+  that nth weekday does not exist in the month.
+
+<sup>1</sup> The `L` and `W` characters can also be combined in the day-of-month field to yield `LW`, which
+translates to "last weekday of the month".
+
+<sup>2</sup> The names of months and days of the week are not case-sensitive. MON is the same as mon.
+
 ## Distributed mode
 
 The scheduler can use its own implementation of `quartz.JobQueue` to allow state sharing.  
 An example implementation of the job queue using the file system as a persistence layer
 can be found [here](./examples/queue/file_system.go).
 
-## Examples
+## Usage example
 
 ```go
 package main
 
 import (
 	"context"
+	"log/slog"
 	"net/http"
+	"os"
 	"time"
 
 	"github.com/reugn/go-quartz/job"
+	"github.com/reugn/go-quartz/logger"
 	"github.com/reugn/go-quartz/quartz"
 )
 
 func main() {
 	ctx, cancel := context.WithCancel(context.Background())
 	defer cancel()
 
-	// create scheduler
-	sched, _ := quartz.NewStdScheduler()
+	// create a scheduler using the logger configuration option
+	slogLogger := slog.New(slog.NewTextHandler(os.Stdout, nil))
+	scheduler, _ := quartz.NewStdScheduler(quartz.WithLogger(logger.NewSlogLogger(ctx, slogLogger)))
 
-	// async start scheduler
-	sched.Start(ctx)
+	// start the scheduler
+	scheduler.Start(ctx)
 
 	// create jobs
 	cronTrigger, _ := quartz.NewCronTrigger("1/5 * * * * *")
@@ -150,25 +184,25 @@ func main() {
 	request, _ := http.NewRequest(http.MethodGet, "https://worldtimeapi.org/api/timezone/utc", nil)
 	curlJob := job.NewCurlJob(request)
 
-	functionJob := job.NewFunctionJob(func(_ context.Context) (int, error) { return 42, nil })
+	functionJob := job.NewFunctionJob(func(_ context.Context) (int, error) { return 1, nil })
 
-	// register jobs to scheduler
-	_ = sched.ScheduleJob(quartz.NewJobDetail(shellJob, quartz.NewJobKey("shellJob")),
+	// register the jobs with the scheduler
+	_ = scheduler.ScheduleJob(quartz.NewJobDetail(shellJob, quartz.NewJobKey("shellJob")),
 		cronTrigger)
-	_ = sched.ScheduleJob(quartz.NewJobDetail(curlJob, quartz.NewJobKey("curlJob")),
-		quartz.NewSimpleTrigger(time.Second*7))
-	_ = sched.ScheduleJob(quartz.NewJobDetail(functionJob, quartz.NewJobKey("functionJob")),
-		quartz.NewSimpleTrigger(time.Second*5))
+	_ = scheduler.ScheduleJob(quartz.NewJobDetail(curlJob, quartz.NewJobKey("curlJob")),
+		quartz.NewSimpleTrigger(7*time.Second))
+	_ = scheduler.ScheduleJob(quartz.NewJobDetail(functionJob, quartz.NewJobKey("functionJob")),
+		quartz.NewSimpleTrigger(5*time.Second))
 
-	// stop scheduler
-	sched.Stop()
+	// stop the scheduler
+	scheduler.Stop()
 
 	// wait for all workers to exit
-	sched.Wait(ctx)
+	scheduler.Wait(ctx)
 }
 ```
 
-More code samples can be found in the examples directory.
+See the examples directory for additional code samples.
 
 ## License
 

examples/readme/main.go

@@ -16,12 +16,12 @@ func main() {
 	ctx, cancel := context.WithCancel(context.Background())
 	defer cancel()
 
-	// create scheduler
+	// create a scheduler using the logger configuration option
 	slogLogger := slog.New(slog.NewTextHandler(os.Stdout, nil))
-	sched, _ := quartz.NewStdScheduler(quartz.WithLogger(logger.NewSlogLogger(ctx, slogLogger)))
+	scheduler, _ := quartz.NewStdScheduler(quartz.WithLogger(logger.NewSlogLogger(ctx, slogLogger)))
 
-	// async start scheduler
-	sched.Start(ctx)
+	// start the scheduler
+	scheduler.Start(ctx)
 
 	// create jobs
 	cronTrigger, _ := quartz.NewCronTrigger("1/5 * * * * *")
@@ -30,19 +30,19 @@ func main() {
 	request, _ := http.NewRequest(http.MethodGet, "https://worldtimeapi.org/api/timezone/utc", nil)
 	curlJob := job.NewCurlJob(request)
 
-	functionJob := job.NewFunctionJob(func(_ context.Context) (int, error) { return 42, nil })
+	functionJob := job.NewFunctionJob(func(_ context.Context) (int, error) { return 1, nil })
 
-	// register jobs to scheduler
-	_ = sched.ScheduleJob(quartz.NewJobDetail(shellJob, quartz.NewJobKey("shellJob")),
+	// register the jobs with the scheduler
+	_ = scheduler.ScheduleJob(quartz.NewJobDetail(shellJob, quartz.NewJobKey("shellJob")),
 		cronTrigger)
-	_ = sched.ScheduleJob(quartz.NewJobDetail(curlJob, quartz.NewJobKey("curlJob")),
+	_ = scheduler.ScheduleJob(quartz.NewJobDetail(curlJob, quartz.NewJobKey("curlJob")),
 		quartz.NewSimpleTrigger(7*time.Second))
-	_ = sched.ScheduleJob(quartz.NewJobDetail(functionJob, quartz.NewJobKey("functionJob")),
+	_ = scheduler.ScheduleJob(quartz.NewJobDetail(functionJob, quartz.NewJobKey("functionJob")),
 		quartz.NewSimpleTrigger(5*time.Second))
 
-	// stop scheduler
-	sched.Stop()
+	// stop the scheduler
+	scheduler.Stop()
 
 	// wait for all workers to exit
-	sched.Wait(ctx)
+	scheduler.Wait(ctx)
 }