inline comments

@MartinSenne please review

some questions and comments for clarification.