UPDATED code climate badge; code samples
first draft
more docs. I hope I don't forget to rebase
adding deprecation warning to method. have to think about this one
more docs
learnt that I should be using JSON.parse