more documentation and api tweaks