Update doc.go

quartz/internal/csm/doc.go

@@ -1,24 +1,42 @@
-// Package csm is and internal packaged focused on solving a single task.
+// "csm" is an internal package focused on solving a single task.
 // Given an arbitrary date and cron expression, what is the first following
-// instant that fits the expression.
+// instant that fits the expression?
 //
-// The method CronStateMachine.NextTriggerTime() (in cron_state_machine.go)
-// calculates the answer. The solution is not mathematically proven to be correct.
-// However, it has been thoroughly tested with multiple complex scenarios.
+// The method CronStateMachine.NextTriggerTime() (cron_state_machine.go)
+// computes the answer. The current solution is not proven to be mathematically correct. 
+// However, it has been thoroughly validated with multiple complex test cases.
 //
 // A date can be though of as a mixed-radix number (https://en.wikipedia.org/wiki/Mixed_radix).
-// First, (1) we must check from most significant (year) to least significant (second) for
+// First, we must check from most significant (year) to least significant (second) for
 // any field that is invalid according to the cron expression, and move it forward to the
-// next valid value. This resets less significant fields and can overflow, advancing more
-// significant fields.
-// This process is implemented in CronStateMachine.findForward() (fn_find_forward.go).
+// next valid value. This resets less significant fields and can overflow; advancing more
+// significant fields. This process is implemented in CronStateMachine.findForward() (fn_find_forward.go).
 //
-// Second, if no fields are changed by this process, we must do (2) the smallest step forward
+// Second, if no fields are changed by this process, we must perform the smallest possible step forward
 // to find the next valid value. This involves moving forward the least significant field (second),
-// taking care to advance the next significant field when the previous overflows.
-// This process is implemented in CronStateMachine.next() (fn_next.go).
+// taking care to advance the next significant field when the previous one overflows. This process is 
+// implemented in CronStateMachine.next() (fn_next.go).
+//
+// In short, the algorithm can be summarized as follows:
+//
+// ┌─────────────────────────────────┐
+// │ findForward() from current date │
+// └───────────────┬─────────────────┘
+//                 │
+//                 │
+//                 │
+//       ┌─────────▼──────────┐
+//       │ Was Date updated?  ├─────Yes─────────────┐
+//       └─────────┬──────────┘                     │
+//                 │                                │
+//                 No                               │
+//                 │                                │
+// ┌───────────────▼────────────────┐           ┌───▼───┐
+// │ find next() smallest timestep  ├───────────► Done  │
+// └────────────────────────────────┘           └───────┘
+//
 //
 // NOTE: Some precautions must be taken as the "day" value does not have a constant radix. It depends
-// on the month and the year. January has 30 days and February 2024 has 29. This is taken into account
-// by the DayNode struct and CronStateMachine.next() (fn_next.go).
+// on the month and the year. January always has 30 days, while February 2024 has 29. This is taken into account
+// by the DayNode struct (day_node.go) and CronStateMachine.next() (fn_next.go).
 package csm