Document comments for push api

Also adds a changelog entry.