more detailed comments and misc code snippets