Clarify the doc for Time.every

[Janiczek]

What unit is the first argument in (it is milliseconds).

[jvoigtlaender]

Actually, saying "milliseconds" there is at odds with the advice further above in the documentation:

Using the Time constants instead of raw numbers is very highly recommended.

For example, for a call Time.every (3 * second) it seems strange to say that it is updated every "3 second milliseconds".

So I think the better change to the documentation here would be not to add "milliseconds" in the text, but instead replace the example expression every 100 in the next line by every (100 * millisecond).

Put differently, the "milliseconds" is an implementation detail. It could be changed at any time (without anything in the current documentation becoming wrong). If people keep to the advice to use the time constants, such a change will have no effect on them. But your documentation proposal would become false then.

[jvoigtlaender]

Actually, saying "milliseconds" there is at odds with the advice further above in the documentation:

Using the Time constants instead of raw numbers is very highly recommended.

For example, for a call Time.every (3 * second) it seems strange to say that it is updated every "3 second milliseconds".

So I think the better change to the documentation here would be not to add "milliseconds" in the text, but instead replace the example expression every 100 in the next line by every (100 * millisecond).

Put differently, the "milliseconds" is an implementation detail. It could be changed at any time (without anything in the current documentation becoming wrong). If people keep to the advice to use the time constants, such a change will have no effect on them. But your documentation proposal would become false then.

[Janiczek]

@jvoigtlaender That makes sense. I agree about replacing every 100 by something more clear. It begs the question "100 of what?" which I wanted to answer in the doc but is really better answered in the code by using an "unit."

[Janiczek]

@jvoigtlaender That makes sense. I agree about replacing every 100 by something more clear. It begs the question "100 of what?" which I wanted to answer in the doc but is really better answered in the code by using an "unit."

[jvoigtlaender]

Cool. If you squash the two commits into one, I will merge.

[jvoigtlaender]

Cool. If you squash the two commits into one, I will merge.

[Janiczek]

I hope force push was the right thing to do :D

[Janiczek]

I hope force push was the right thing to do :D