"Why is function X not documented somewhere?"
Because there are thousands of functions available in Moodle core and it's hard to figure out a way of organising the documentation of them in such a way as to make it easier to find functions in the documentation than it is to simply look at existing example code in core to find them (or to look for other functions in the same file as one that is close to what you wanted).
If you think there is a useful place you could add this function to the documentation, then feel free to pop over to https://docs.moodle.org/dev/Main_Page and add it (it's a wiki - anyone can create an account and edit it).
If you think there is a useful place you could add this function to the documentation, then feel free to pop over to https://docs.moodle.org/dev/Main_Page and add it (it's a wiki - anyone can create an account and edit it).