documentation + fix unconsistency in API
this may brake existing applications