more docs and assertions