some re-wording, and better params'
fix JS bug
updated ruby documentation for API