Introduce a new API and deprecate the old

Also add YARD inline documentation throughout.