improved docs on the main interfaces