docs($resource): document Resource#toJSON

[jrvidal]

Document the toJSON method of Resource instances as part of its public API.

[gkalpak]

Thx for submit this! Could you expand a little bit on when toJSON is used and what it does? Maybe add a link to MDN.

[jrvidal]

Could you expand a little bit on when toJSON is used and what it does? Maybe add a link to MDN.

Will do 👍

I have just realized that toJSON does not remove $cancelRequest, so strictly speaking, it doesn't return a "simple object without the extra methods". Do you think it is pertinent to modify toJSON to do that, and if so, is it OK to do it in this PR?

[gkalpak]

toJSON is not a general purpose function - it's sole purpose is facilitating proper conversion to JSON. As such, it makes sense to do the least amount of work necessary. Functions are not serialized to JSON, so $cancelRequest is not deleted on purpose.

[jrvidal]

Gotcha, I will update the docs accordingly.

[jrvidal]

Notice however how this behavior means that the workaround I mentioned in #14637, where I tried to use a toJSON call as a way of getting "just the data", is not valid. In any case, documenting this method improves the situation so at least we know where we stand.

[jrvidal]

I rebased my commit with a better description.