add more docs and assertions