Polish documentation for the queue module

Ensure that the first sentence describing each function makes sense
by itself when shown in the Summary part of the documentation.

Add examples for all functions. Ensure that the example don't show
the internal representaion of queues.

While at it, get rid of old-style `catch` from the test sutie, remove
comments for documented functions, remove out-commented code, and do
some other minor clean ups.

Author: bjorng