When covering custom triggers, an interesting example could be a trigger wrapper that excludes holidays: Cron task that runs every weekday at midnight, except "holidays" (defined by some kind of lookup table).

RecurringMessage::trigger(
    new ExcludeHolidaysTrigger( // our custom trigger wrapper
        CronExpressionTrigger::fromSpec('@daily'),
    ),
    new SendDailySalesReports(),
);

And something like the following for the custom trigger (untested):

class ExcludeHolidaysTrigger implements TriggerInterface
{
    public function __construct(private TriggerInterface $inner)
    {
    }

    public function __toString(): string
    {
        return $this->inner.' (except holidays)';
    }

    public function getNextRunDate(\DateTimeImmutable $run): ?\DateTimeImmutable
    {
        if (!$nextRun = $this->inner->getNextRunDate($run)) {
            return null;
        }

        while (!$this->isHoliday($nextRun) { // loop until we get the next run date that is not a holiday
            $nextRun = $this->inner->getNextRunDate($nextRun);
        }

        return $nextRun;
    }

    private function isHoliday(\DateTimeImmutable $timestamp): bool
    {
        // app specific logic to determine if $timestamp is on a holiday
        // returns true if holiday, false otherwise
    }
}

As far as I am aware, we never use "us". You may replace by "allowing you to retain control". Same for "our", to be replace by "your"

I think this title can be removed

(spaces between are required)

You may actually put this in the code snippet above, something like

// optionally specify the timezone to run the job on
RecurringMessage::cron...

(spaces between are required)

This part isn't quite correct. What you're describing is the standard cron aliases

• @daily
• @monthly
• etc...

Hashed aliases are different in that they create a random but deterministic standard cron expression based on some context (in this case, the message's __toString() value).

At some point later in the doc, we need to discuss the importance of not having many tasks all run at the same time (ie 10 jobs at 00:00 every day). The jitter trigger wrapper is one solution, another is hashed cron expressions. I think here is where we should describe this feature.

Why don't you drop this section for now (or just show more examples of standard cron expressions) and I'll create a follow-up PR explaining hashed expressions. I originally ported this code to Symfony and use it quite extensively.

We need to note that dragonmantank/cron-expression is required to use the cron expression trigger.

Might also be nice to have a link to https://crontab.guru/ to help users construct/understand cron expressions.

The --all option has been added in 6.4. Maybe we should keep it for another PR ?

Seems like --date has been added at the same time, 6.4 too

IIUC, timezone for cron expression trigger is a 6.4 feature

Those attributes have been added in 6.4

Methods remove and clear have been added in 6.4

Events have been added in 6.4

Let's move this later. I haven't learned how to create recurring message yet.

The "considered as a message" doesn't make sense to me. Does schedule call them "messages" but the user thinks of them as tasks? If so, how about:

At its core, scheduler allows you to create a task (called a message) that is executed by a service and repeated on some schedule.

I understand your point of view. Indeed, what I meant to say is: 'At its core, the principle is straightforward: a task, treated as a message by the Scheduler, must be handled by a service, and this cycle should be repeated'

If we can think of a more realistic name, that would be awesome :)

I'm not sure we should mention this. Memoizing is a pretty technical term and probably creating a schedule is not a heavy thing anyway.

Are there any other types of messages that you would schedule? Suggestion for the title:

Scheduling Recurring Messages

And, I like this section. This is where we get into the meat of things

Is the $this->schedule part of the memoization? I really need to be convinced that it is VERY important to keep this detail

We haven't talked about workers or messenger:consume yet. I think we should at least show them. The story I want to see is:

A) Creating a message & handler of some sort (this can be very quick and point to Messenger, and the handler can be empty, but we should show it)
B) Creating a schedule and setting up this message in a recurring way
C) Running messenger:consume - and talking a bit about how that works and what to expect.

To keep for 6.4 PR

#19244 (comment)
It'll be updated in #19292 + version added in 6.3