I think this is excessively verbose for such a simple function, especially the addition of examples.
There are many APIs which are hundreds of times more complicated which don't have this level of detailing, and I would argue such manual pages have the correct tone and complexity. It stops feeling like a historically+adapted BSD manual page.
