while we're on the topic of documentation
improve deprecation docs. remove repeat decorator