begin docs for filtering, adjust API to docs