vm_page_advise(9): expand from vm_page_dontneed(9)

[mhorne]

Summary

The function was renamed and expanded some time ago. Describe its
current functionality.

[markj]

I'm kind of skeptical that this man page is useful at all. vm_page_advise() really exists just to implement the madvise() system call, it's not going to be called externally. And, it's just a piece of that system call. vm_map_madvise(), vm_object_madvise(), pmap_advise() also implement parts of madvise(); why are they not documented as well? IMHO it's somewhat more useful to focus on improving madvise.3, which is user-facing and describes the user-visible effect for each type of advice. With a high-level understanding of what MADV_FREE etc. are supposed to do, it becomes easier to understand why vm_page_advise() does what it does.

[markj]

To be clear, I don't object to the patch (certainly it's worth removing the stale link), but I think it is much more useful to document the higher-level components of the VM system, and use code comments to explain "interesting" aspects of the implementation.

[alc]

In D42512#970386, @markj wrote:

I'm kind of skeptical that this man page is useful at all. vm_page_advise() really exists just to implement the madvise() system call, it's not going to be called externally. And, it's just a piece of that system call. vm_map_madvise(), vm_object_madvise(), pmap_advise() also implement parts of madvise(); why are they not documented as well? IMHO it's somewhat more useful to focus on improving madvise.3, which is user-facing and describes the user-visible effect for each type of advice. With a high-level understanding of what MADV_FREE etc. are supposed to do, it becomes easier to understand why vm_page_advise() does what it does.

I agree.