added some comments and documentation for #235