a couple new methods, doc improvements, tiny optimization