added comments and minor API changes