Improve filter documentation
Improve filter documentation

This improves the filter documentation by making the return of
``filter`` clearer, adding helpful links, and cleaning up the examples
so they're more focused.

willkg/markus