Tweaks to docs on error responses

[pablobm]

Wut?

Recently I was looking at how to get errors to work, and found the docs slightly confusing. I decided to give it a go and see if I could improve them in some way. This is what I got so far.

Does this make sense? I probably can add some other details and make corrections, but I wanted to fly this past you before spending more time on it. I'm happy to take any feedback you may have.

Rationale

I removed the example provided at addon/-private/system/model/errors.js because I feel it can lead to confusion making people think DS.Errors actually expects responses in a specific format.

I think the docs at addon/adapters/rest.js need to be more explicit at to what exactly it expects.

I think the JSON example belongs in addon/serializers/json.js, with details of what keys are actually used. The JSON-API spec lists a few keys that "MAY" appear here, and users need information as to which ones ember-data actually uses.

Incidentally...

I have no idea of how to generate the docs from this code. I figured out how to do it for ember, using yuidoc, but I don't know what the procedure is for ember-data. Hence, I haven't been able to read the results, and my Markdown may have errors I haven't been able to spot.

[bmac]

Looks great @pablobm. 👍

[bmac]

To generate the API docs there is a rake generate_ember_data_docs command in the website repo that assumes the Ember Data repo is an a folder called ember-data that lives adjacent to the folder where the website is checked out.

[pangratz]

Hmm, IMHO "be passed along as a black box, wrapped ..." is a little confusing here. What do you think of "be passed along as is, wrapped ..."?

[pablobm]

I like

[pablobm]

OK. I'll have another pass during the weekend. Thank you for the feedback.

[pablobm]

I'm happy with this now. Any other comments?

[pangratz]

LGTM, can you squash all commits into 1, prefixed with [DOC]? Thanks!

[pablobm]

@pangratz: done

[bmac]

Thanks @pablobm.