first pass at YARD documentation

Basically just added return types (as best I could), for starters.    View it with:

```
gem install yard
yard server
open http://localhost:8808
```

Didn't fix errors in README - see #29.