add #run as a public method, improve docs.