improving intro and scopes doc
controllers doc minors
Merge pull request #626 from csokol/improving-rest-doc

improving intro and scopes doc