cleanup serializer documentation (#6575)

packages/adapter/addon/index.js

@@ -1,4 +1,6 @@
 /**
+ * 
+ * 
   @module @ember-data/adapter
   @main @ember-data/adapter
 */
@@ -56,6 +58,7 @@ import EmberObject from '@ember/object';
   For an example of the implementation, see `RESTAdapter`, the
   included REST adapter.
 
+  @module @ember-data/adapter
   @class Adapter
   @extends EmberObject
 */
@@ -77,6 +80,7 @@ export default EmberObject.extend({
     });
     ```
 
+    @deprecated
     @property defaultSerializer
     @type {String}
   */

packages/serializer/addon/index.js

@@ -1,6 +1,5 @@
 /**
   @module @ember-data/serializer
-  @main @ember-data/serializer
 */
 
 import EmberObject from '@ember/object';

packages/store/addon/-private/ts-interfaces/minimum-serializer-interface.ts

@@ -1,26 +1,26 @@
 /**
   ## Overview
 
-  In order to properly manage and present your data, `EmberData`
+  In order to properly manage and present your data, EmberData
   needs to understand the structure of data it receives.
 
   `Serializers` convert data between the server's API format and
-  the format `EmberData` understands.
+  the format EmberData understands.
 
-  Data received from an API response is `"normalized"` into 
+  Data received from an API response is **normalized** into 
   [JSON:API](https://jsonapi.org/) (the format used internally
-  by `EmberData`), while data sent to an API is `"serialized"`
+  by EmberData), while data sent to an API is **serialized**
   into the format the API expects.
 
   ### Implementing a Serializer
 
   There are only two required serializer methods, one for
-  normalizing data from the server API format into `JSON:API`, and
-  another for serializing records via `Snapshot`s into the expected
+  normalizing data from the server API format into JSON:API, and
+  another for serializing records via `Snapshots` into the expected
   server API format.
 
   To implement a serializer, export a class that conforms to the structure
-  described by the [MinimumSerializerInterface](MinimumSerializerInterface)
+  described by the [MinimumSerializerInterface](/ember-data/release/classes/MinimumSerializerInterface)
   from the `app/serializers/` directory. An example is below.
 
   ```ts
@@ -44,10 +44,10 @@
  ```
 
 
-  #### Serializer Resolution
+  ### Serializer Resolution
 
   `store.serializerFor(name)` will lookup serializers defined in
-  `app/serializers` and return an instance. If no serializer is found, an
+  `app/serializers/` and return an instance. If no serializer is found, an
   error will be thrown.
 
   `serializerFor` first attempts to find a serializer with an exact match on `name`,
@@ -61,9 +61,9 @@
   //   app/serializers/application.js
   ```
 
-  Most requests in `ember-data` are made with respect to a particular `type` (or `modelName`)
+  Most requests in EmberData are made with respect to a particular `type` (or `modelName`)
   (e.g., "get me the full collection of **books**" or "get me the **employee** whose id is 37"). We
-  refer to this as the *"primary"* resource `type`.
+  refer to this as the **primary** resource `type`.
   
   Typically `serializerFor` will be used to find a serializer with a name matching that of the primary
   resource `type` for the request, falling back to the `application` serializer for those types that
@@ -80,11 +80,11 @@
 
   ### Using a Serializer
 
-  Any serializer in `app/serializers` can be looked up by `name` using `store.serializerFor(name)`.
+  Any serializer in `app/serializers/` can be looked up by `name` using `store.serializerFor(name)`.
 
   ### Default Serializers
 
-  For applications whose APIs are *very close to* or *exactly* the `REST` or `JSON:API`
+  For applications whose APIs are *very close to* or *exactly* the **REST** format or **JSON:API**
   format the `@ember-data/serializer` package contains implementations these applications can
   extend. It also contains a simple `JSONSerializer` for serializing to/from very basic JSON objects.
 
@@ -97,7 +97,6 @@
 
   @module @ember-data/serializer
   @main @ember-data/serializer
-  @class MinimumSerializerInterface
   @public
 */
 
@@ -110,6 +109,17 @@ import { Dict } from './utils';
 
 type OptionsHash = Dict<any>;
 
+/**
+  The following documentation describes the methods an application
+  serializer should implement with descriptions around when an
+  application might expect these methods to be called.
+
+  Methods that are not required are marked as **optional**.
+
+  @module @ember-data/serializer
+  @class MinimumSerializerInterface
+  @public
+*/
 interface Serializer {
   /**
    * This method is responsible for normalizing the value resolved from the promise returned
@@ -128,18 +138,18 @@ interface Serializer {
    *
    * @method normalizeResponse
    * @public
-   * @param {Store} store - the store service that initiated the request being normalized
-   * @param {ShimModelClass} schema - An object with methods for accessing information about
+   * @param {Store} store The store service that initiated the request being normalized
+   * @param {ShimModelClass} schema An object with methods for accessing information about
    *  the type, attributes and relationships of the primary type associated with the request.
-   * @param {JSONObject} rawPayload - The raw JSON response data returned from an API request.
+   * @param {JSONObject} rawPayload The raw JSON response data returned from an API request.
    *  This correlates to the value the promise returned by the adapter method that performed
    *  the request resolved to.
-   * @param {string|null} id - For a `findRecord` request, this is the `id` initially provided
-   *  in the call to `store.findRecord`. Else this value is `null`.
-   * @param {'findRecord' | 'queryRecord' | 'findAll' | 'findBelongsTo' | 'findHasMany' | 'findMany' | 'query' | 'createRecord' | 'deleteRecord' | 'updateRecord'} requestType - The
+   * @param {string|null} id For a findRecord request, this is the id initially provided
+   *  in the call to store.findRecord. Else this value is null.
+   * @param {'findRecord' | 'queryRecord' | 'findAll' | 'findBelongsTo' | 'findHasMany' | 'findMany' | 'query' | 'createRecord' | 'deleteRecord' | 'updateRecord'} requestType The
    *  type of request the Adapter had been asked to perform.
    *
-   * @returns {JsonApiDocument} - a document following the structure of a [JSON:API Document](https://jsonapi.org/format/#document-structure).
+   * @returns {JsonApiDocument} a document following the structure of a JSON:API Document.
    */
   normalizeResponse(
     store: Store,
@@ -173,7 +183,7 @@ interface Serializer {
    *
    * @method serialize
    * @public
-   * @param {Snapshot} snapshot - A Snapshot for the record to serialize
+   * @param {Snapshot} snapshot A Snapshot for the record to serialize
    * @param {object} [options]
    */
   serialize(snapshot: Snapshot, options?: OptionsHash): JSONObject;
@@ -182,7 +192,7 @@ interface Serializer {
    * This method is intended to normalize data into a [JSON:API Document](https://jsonapi.org/format/#document-structure)
    * with a data member containing a single [Resource](https://jsonapi.org/format/#document-resource-objects).
    *
-   * - `type` should be formatted in the `singular` `dasherized` `lowercase` form
+   * - `type` should be formatted in the singular, dasherized and lowercase form
    * - `members` (the property names of attributes and relationships) should be formatted
    *    to match their definition in the corresponding `Model` definition. Typically this
    *    will be `camelCase`.
@@ -196,7 +206,7 @@ interface Serializer {
    *
    * This method may be called when also using the `RESTSerializer`
    * when `serializer.pushPayload` is called by `store.pushPayload`.
-   * It is recommended to use `store.push` over `store.pushPayload` after normalizing
+   * However, it is recommended to use `store.push` over `store.pushPayload` after normalizing
    * the payload directly.
    *
    * Example:
@@ -223,21 +233,22 @@ interface Serializer {
    * @method normalize [OPTIONAL]
    * @public
    * @optional
-   * @param {ShimModelClass} schema - An object with methods for accessing information about
+   * @param {ShimModelClass} schema An object with methods for accessing information about
    *  the type, attributes and relationships of the primary type associated with the request.
-   * @param {JSONObject} rawPayload - Some raw JSON data to be normalized into a [JSON:API Resource](https://jsonapi.org/format/#document-resource-objects).
-   * @param {string} [prop] - When called by the `EmbeddedRecordsMixin` this param will be the
+   * @param {JSONObject} rawPayload Some raw JSON data to be normalized into a JSON:API Resource.
+   * @param {string} [prop] When called by the EmbeddedRecordsMixin this param will be the
    *  property at which the object provided as rawPayload was found.
-   * @returns {SingleResourceDocument} - A [JSON:API Document](https://jsonapi.org/format/#document-structure)
-   *  containing a single [JSON:API Resource](https://jsonapi.org/format/#document-resource-objects)
+   * @returns {SingleResourceDocument} A JSON:API Document
+   *  containing a single JSON:API Resource
    *  as its primary data.
    */
   normalize?(schema: ShimModelClass, rawPayload: JSONObject, prop?: string): SingleResourceDocument;
 
   /**
    * When using `JSONAPIAdapter` or `RESTAdapter` this method is called
-   * by `adapter.updateRecord` and `adapter.createRecord` if `Serializer.serializeIntoHash`
-   * is not implemented.
+   * by `adapter.updateRecord` and `adapter.createRecord` if `serializer.serializeIntoHash`
+   * is implemented. If this method is not implemented, `serializer.serialize`
+   * will be called in this case.
    *
    * You can use this method to customize the root keys serialized into the payload.
    * The hash property should be modified by reference.
@@ -265,11 +276,11 @@ interface Serializer {
    * @method serializeIntoHash [OPTIONAL]
    * @public
    * @optional
-   * @param hash - a top most object of the request payload onto
+   * @param hash A top most object of the request payload onto
    *  which to append the serialized record
-   * @param {ShimModelClass} schema - An object with methods for accessing information about
+   * @param {ShimModelClass} schema An object with methods for accessing information about
    *  the type, attributes and relationships of the primary type associated with the request.
-   * @param {Snapshot} snapshot - A Snapshot for the record to serialize
+   * @param {Snapshot} snapshot A Snapshot for the record to serialize
    * @param [options]
    * @returns {void}
    */
@@ -279,10 +290,14 @@ interface Serializer {
    * This method allows for normalization of data when `store.pushPayload` is called
    * and should be implemented if you want to use that method.
    *
-   * The output should be a [JSON:API Document](https://jsonapi.org/format/#document-structure)
+   * The method is responsible for pushing new data to the store using `store.push`
+   * once any necessary normalization has occurred, and no data in the store will be
+   * updated unless it does so.
+   *
+   * The normalized form pushed to the store should be a [JSON:API Document](https://jsonapi.org/format/#document-structure)
    * with the following additional restrictions:
    *
-   * - `type` should be formatted in the `singular` `dasherized` `lowercase` form
+   * - `type` should be formatted in the singular, dasherized and lowercase form
    * - `members` (the property names of attributes and relationships) should be formatted
    *    to match their definition in the corresponding `Model` definition. Typically this
    *    will be `camelCase`.
@@ -308,12 +323,12 @@ interface Serializer {
    * @method pushPayload [OPTIONAL]
    * @public
    * @optional
-   * @param {Store} store - the store service that initiated the request being normalized
-   * @param {JSONObject} rawPayload - The raw JSON response data returned from an API request.
+   * @param {Store} store The store service that initiated the request being normalized
+   * @param {JSONObject} rawPayload The raw JSON response data returned from an API request.
    *  This JSON should be in the API format expected by the serializer.
-   * @returns {JsonApiDocument} - a document following the structure of a [JSON:API Document](https://jsonapi.org/format/#document-structure)
+   * @returns {void}
    */
-  pushPayload?(store: Store, rawPayload: JSONObject): JsonApiDocument;
+  pushPayload?(store: Store, rawPayload: JSONObject): void;
 }
 
 export default Serializer;