[FLINK-12092] [docs]Clarify when onTimer(...) is called

[an0]

No description provided.

[flinkbot]

Thanks a lot for your contribution to the Apache Flink project. I'm the @flinkbot. I help the community
to review your pull request. We will use this comment to track the progress of the review.

Automated Checks

Last check on commit 81f7ac0 (Wed Dec 04 14:51:28 UTC 2019)

Warnings:

• Documentation files were touched, but no .zh.md files: Update Chinese documentation or file Jira ticket.
• This pull request references an unassigned Jira ticket. According to the code contribution guide, tickets need to be assigned before starting with the implementation work.

_{Mention the bot in a comment to re-run the automated checks.}

Review Progress

• ❓ 1. The [description] looks good.
• ❓ 2. There is [consensus] that the contribution should go into to Flink.
• ❗ 3. Needs [attention] from.
  • Needs attention by @alpinegizmo
• ❓ 4. The change fits into the overall [architecture].
• ❓ 5. Overall code [quality] is good.

Please see the Pull Request Review Guide for a full explanation of the review process.

The Bot is tracking the review progress through labels. Labels are applied according to the order of the review items. For consensus, approval by a Flink committer of PMC member is required

Bot commands

The @flinkbot bot supports the following commands:

• @flinkbot approve description to approve one or more aspects (aspects: description, consensus, architecture and quality)
• @flinkbot approve all to approve all aspects
• @flinkbot approve-until architecture to approve everything until architecture
• @flinkbot attention @username1 [@username2 ..] to require somebody's attention
• @flinkbot disapprove architecture to remove an approval you gave earlier

[tzulitai]

I agree we should explain what "when time is reached" means for both event and processing time, but I'm not sure of the actual changes in the PR.

Maybe something along the lines of:

When a timer's particular time is reached, the `onTimer(...)` method is called; for processing time, this would mean __________, while for event time, this would mean ______________.

[tzulitai]

@alpinegizmo what do you think?

[alpinegizmo]

I suggest:

With event-time timers, the onTimer(...) method is called when the current watermark is advanced up to or beyond the timestamp of the timer, while with processing-time timers, onTimer(...) is called when wall clock time reaches the specified time.

[an0]

I don't have a strong opinion about wording as long as it explains things clearly.

[tzulitai]

@an0 can you update the PR to what David suggested?

[an0]

Sure. Done.

[an0]

@tzulitai Is it mergeable?

[tzulitai]

@flinkbot attention @alpinegizmo

[dawidwys]

Hi @an0 thank you for your contribution and sorry for a late reply. I will merge it now.