Document the semaphore implementation better

[bugaevc]

The semaphore implementation is rather complicated. The trick a mutex uses to avoid losing wakeups is already tricky enough ("futexes are tricky!") that it took me a long time to understand; the semaphore is far more complex & trickier. It needs to wake multiple threads simultaneously, and the responsibility for waking them is split between threads calling up() and threads calling down() (waking up anyone in down() is very unusual!), and it oftentimes sets the need_to_wake_bit even when there are remaining slots. This all needs more docs/comments.