On Wed, 21 Aug 2024 12:25:48 GMT, Kevin Walls <kev...@openjdk.org> wrote:
>> You beat me to it. We specify some methods (close, dispose, ...) as >> idempotent. Specifying a getter as non-idempotent looks very strange here. >> >> I can't tell if you are looking to specify implementation behavior (as David >> asks) or whether you want to provide advice for users of this API, in which >> case an apiNote may be the tag you need. > > 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". ------------- PR Review Comment: https://git.openjdk.org/jdk/pull/20546#discussion_r1725090806
