Polish documentation for the lists modules

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

Add examples to functions that lacking examples.

While at it, also remove comments for documented functions, and
remove out-commented code, and do some other minor clean ups.