updated markdown and comments