poll: Document reentrancy restriction on before()

If the before() callback might modify the wanted fds or timeouts of
other poll users, the loop over poll users in run() might produce
wrong answers.  Therefore, document that this is not permitted.  (All
of the existing before() implementations are indeed fine.)

Also, document a couple of features of the afterpoll_fn interface.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>