Adjustments to documentation

This PR includes all adjustments to the documentation listed from

https://trello.com/c/lAGH6360/159-improve-data-model-documentation

@jh-bate @jebeck @kentquirk @nicolashery @ianjorgensen 

Please give this a once over, see if there is anything that could be explained better or just differently.  If you can think of an example that you had a question about what would happen, providing that would also be useful (I can fill in what will actually happen).
Both Carelink and Insulet report recommendations at a finer grain than this, and the docs want to see the breakdown.

Proposal:
```
"recommendedDose": {
  "forCarbs": number_of_units_recommended,
  "forCorrection": number_of_units_recommended
}
```

If a device doesn't report both, I'd say `"recommendedDose": number_of_units_recommended` could be used. We can check for objecthood to see what to expect.