move function out to top level and add doc