apply review comments. refs #389
improve head notes of docs about scala-json. refs #389