clarify interval and timeout for http health check

[hannahhearth]

Fixes #2977

See source code.

[banks]

Slight wording change, but thanks this is clearer

[hannahhearth]

Thanks @banks, how does it look now?

[banks]

Great, thanks!

[pierresouchay]

LGTM

[pearkes]

I feel like we can get this merged, @opihana?

[valentin-krasontovitsch]

Sorry to give my 2 cents, but I feel like the comment in the source code does not reflect the logic in the source code.

Let me quote the block in question (which conveniently is also linked above):

// For long (>10s) interval checks the http timeout is 10s, otherwise the
// timeout is the interval. This means that a check *should* return
// before the next check begins.
if c.Timeout > 0 && c.Timeout < c.Interval {
	c.httpClient.Timeout = c.Timeout
} else if c.Interval < 10*time.Second {
	c.httpClient.Timeout = c.Interval
}

The improved docs describe the source code, so I think it would make sense to correct the comment as well (or remove it - some people might say that that's why we have documentation in separate files, so we don't need [to maintain] comments like this) - I personally think it should just be scratched though, the logic is clear from the code.

[freddygv]

We're going to change the behavior so that we use the user provided timeout rather than restricting it based on the interval.

See #6094