improved docs to describe pagination