documented and cleaned-up API snapshot