update some docs and comments

cc @lzyzsd