more changes to allow filtering, as well as documentation