adds comments
runs rake twice to avoid Rails 4 bug
documentation updates