[DOC] Correct `RESTAdapter` namespace documentation

[btecu]

Certain methods on the RESTAdapter are namespaced improperly in the documentation: https://api.emberjs.com/ember-data/3.12/classes/RESTAdapter/methods/urlForFindMany?anchor=urlForFindRecord

[btecu]

Is not a huge deal, I can close this if there's no easy way to fix it.

[runspired]

I think the best solution here is to overwrite the docs within the RESTAdapter

[btecu]

Is there an example of what that would look like?

[runspired]

@btecu sure. The way docs work, while they live with the code they document they aren't actually coupled to it in anyway. You can have doc comments for methods, classes, and even full packages that don't actually exist in your code.

In our case, we want to take advantage of that to alter the docs for inherited methods. So for example:

import RESTAdapter from './rest';

/**
 @module @ember-data/adapter
 @class JSONAPIAdapter
*/
export default class JSONAPIAdapter extends RESTAdapter {}

@module here tells us this documentation is part of the @ember-data/adapter package. @class here tells us this documentation belongs to the JSONAPIAdapter class.

Until another @module or @class is discovered in the file, the documentation that follows will be appended to this class.

So for instance

import RESTAdapter from './rest';

/**
 @module @ember-data/adapter
 @class JSONAPIAdapter
*/
export default class JSONAPIAdapter extends RESTAdapter {
  /**
    @property namespace
    @type {String} the namespace for API requests issued by this adapter
  */
  /**
    @method createRecord
    @param {Store} store the store instance asking for this record to be created
    @param {ModelSchema} schema schema information for the primaryType for this request
    @param {Snapshot} snapshot a snapshot of locally available information to save as part of this request
  */
   /**
    @method updateRecord
    @param {Store} store the store instance asking for this record to be created
    @param {ModelSchema} schema schema information for the primaryType for this request
    @param {Snapshot} snapshot a snapshot of locally available information to save as part of this request
  */
  async updateRecord(store, modelSchema, snapshot) {
    const response = await fetch('./user/1', { method: 'PATCH', data: {} });
    return response.toJSON();
  }
}

note how above I added docs for a property and a two methods, but only defined one of the methods. Our API docs will include all of these for the class. So in this way we can easily "fill in" the API docs for anything inherited without actually needing to implement any methods :)

Hope this helps!

[MelSumner]

@btecu @runspired what needs to happen to move this PR forward? Thank you for your work!

[runspired]

@MelSumner @locks the docs need to be copied forward to RESTAdapter and their examples updated to show rest-ish examples. Probably best done as a new PR at this point.