- first finalised version of API doc
 - introduced error throws