improved docs and compatibility