documentation and method signature changes to provide better context for usage