incorporate Wei's comments to docs