add comments and clarifications