more comments and minor spec changes