reviewed and documented callback API