updated interface + docs
correct return values and docs