RFR: 8330144: Revise os::free_memory() [v2]

[Thomas Stuefe]

On Wed, 10 Jul 2024 17:58:25 GMT, Robert Toyonaga <duke at openjdk.org> wrote:

>> src/hotspot/os/windows/os_windows.cpp line 3896:
>> 
>>> 3894: 
>>> 3895: void os::pd_realign_memory(char *addr, size_t bytes, size_t alignment_hint) { }
>>> 3896: void os::pd_disclaim_memory(char *addr, size_t bytes) { }
>> 
>> Give us a little comment about what this API does?
>> 
>> "Hints to the OS that the memory is not needed anymore and can be reclaimed by the OS; will destroy memory content; it will be re-aquired on touch, no explicit committing needed"
>> 
>> Something like that
>
> Ok I've added a comment with a description. 
> 
> Is it good practice to add these types of descriptions in the shared code header files (os.hpp), in the platform dependent code (os_linux.hpp), or both? I see some examples of all 3 cases, but I'm wondering if there's a best practice.

There is no common format. Sun did not comment any APIs in the beginning. I usually do it above the prototype in the hpp file, because then IDEs cab pick it up and show you the description in tooltips.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/20080#discussion_r1673405671