RFR: 8335625: Update Javadoc for GetCpuLoad [v2]

[David Holmes]

On Wed, 21 Aug 2024 13:49:08 GMT, Joakim Nordström <jnordstrom at openjdk.org> wrote:

>> Ok yes maybe "not idempotent" isn't a great term here.
>> Just removing that phrase, "This method is not idempotent.", this would still be a helpful update.
>
> I want to provide advice for how this API should be used.
> 
> The "recent period of time observed" is vague (Who's the observer? Who decides the "recent period"? The API user or the JVM?). In essence it is the time between two consecutive calls, but that is not very clear from the description -- this has been seen to cause confusion.
> 
> I hesitated to add "idempotent", but also I felt that it added something. Without it, the rest of the sentence is basically just the same words as in the first paragraph, so they can be easily missed. Also, the best practices I've seen is that "getters" should be idempotent, so stating this one isn't signals there's something to take note of here.
> 
> Adding `@apiNote` might be enough of signal. Have updated with the tag and removed "idempotent".

> "Idempotence is the property of certain operations in mathematics and computer science whereby they can be applied multiple times without changing the result beyond the initial application. "

So the notion of idempotency on a getter method just doesn't make sense in general  and in this case in particular as you calculate a new result each time.

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/20546#discussion_r1725887348