Backport #6449 to LTS 3.12 (#6524)

* [FIX DOCS] Docs updates for Packages to fix missing docs and broken links (#6449)

* remove ember-data and DS namespace/module
* eliminate usage of DS.Store in the documentation
* improve Store documentation
* configure Store docs to be the main docs for the @ember-data/store package
* cleanup Model docs
* fix adapter/serializer location and main docs
* cleanup DS. usage in docs
* Fix/ds docs (#6456)
* [DOCS] Fix some links (#6507)

Co-Authored-By: Gaurav Munjal <[email protected]>

* fix lint

.eslintignore

@@ -3,6 +3,7 @@ packages/*/blueprints/*/*files/
 vendor/
 
 # compiled output
+/packages/-ember-data/docs/
 dist
 tmp
 
@@ -13,6 +14,7 @@ node_modules
 # misc
 /coverage/
 !.*
+/.yarn/
 
 # ember-try
 .node_modules.ember-try

.eslintrc.js

@@ -31,6 +31,11 @@ module.exports = {
     'no-irregular-whitespace': 'error',
     'no-undef': 'error',
     'no-eq-null': 'error',
+    'no-console': 'error', // no longer recommended in eslint v6, this restores it
+
+    // Too many false positives
+    // See https://github.com/eslint/eslint/issues/11899 and similar
+    'require-atomic-updates': 'off',
   },
   globals: {
     heimdall: true,
@@ -48,7 +53,7 @@ module.exports = {
         '.mocharc.js',
         '.eslintrc.js',
         '.prettierrc.js',
-        'bin/*.js',
+        'bin/*',
         'packages/-build-infra/src/**/*.js',
         'packages/-test-infra/src/**/*.js',
         'packages/*/ember-cli-build.js',
@@ -87,5 +92,26 @@ module.exports = {
         mocha: true,
       },
     },
+    {
+      files: ['packages/-ember-data/node-tests/docs/*.js'],
+
+      env: {
+        qunit: true,
+        es6: false,
+      },
+    },
+
+    // bin files
+    {
+      files: ['bin/*'],
+      // eslint-disable-next-line node/no-unpublished-require
+      rules: Object.assign({}, require('eslint-plugin-node').configs.recommended.rules, {
+        'no-console': 'off',
+        'no-process-exit': 'off',
+        'node/no-extraneous-require': 'off',
+        'node/no-unpublished-require': 'off',
+        'node/shebang': 'off',
+      }),
+    },
   ],
 };

CHANGELOG.md

@@ -1863,7 +1863,7 @@ post.constructor.typeKey => postSnapshot.typeKey
 If you need to access the underlying record of a snapshot you can do so by
 accessing `snapshot.record`.
 
-The full API reference of `DS.Snapshot` can be found [here](https://emberjs.com/api/data/classes/DS.Snapshot.html).
+The full API reference of `DS.Snapshot` can be found [here](https://api.emberjs.com/ember-data/release/classes/Snapshot).
 
 #### Changes
 
@@ -2097,7 +2097,7 @@ to set metadata.
 
 ##### `ManyArray`s are no longer `RecordArray`s
 
-[ManyArray](https://emberjs.com/api/data/classes/DS.ManyArray.html),
+[ManyArray](https://api.emberjs.com/ember-data/release/classes/ManyArray),
 the object Ember Data uses to represent `DS.hasMany` relationships has
 been changed so it no longer extends from `RecordArray`. This means if
 you were relying on the RecordArray's `content` property to access the

bin/publish.js

@@ -142,11 +142,7 @@ function assertGitIsClean() {
   }
 
   let expectedChannelBranch =
-    options.distTag === 'canary'
-      ? 'master'
-      : options.distTag === 'latest'
-      ? 'release'
-      : options.distTag;
+    options.distTag === 'canary' ? 'master' : options.distTag === 'latest' ? 'release' : options.distTag;
 
   if (options.channel === 'lts') {
     expectedChannelBranch = `lts-${semver.major(options.currentVersion)}-${semver.minor(options.currentVersion)}`;

packages/-ember-data/addon/-private/core.js

@@ -1,30 +1,26 @@
+/**
+ @module @ember-data
+ @main @ember-data
+ */
+
 import Namespace from '@ember/application/namespace';
 import Ember from 'ember';
 import VERSION from 'ember-data/version';
 
 /**
-  @module ember-data
-*/
-
-/**
-  All Ember Data classes, methods and functions are defined inside of this namespace.
-
-  @class DS
-  @static
-*/
+ * @property VERSION
+ * @public
+ * @static
+ * @for @ember-data
+ */
 
-/**
-  @property VERSION
-  @type String
-  @static
-*/
 const DS = Namespace.create({
   VERSION: VERSION,
   name: 'DS',
 });
 
 if (Ember.libraries) {
-  Ember.libraries.registerCoreLibrary('Ember Data', DS.VERSION);
+  Ember.libraries.registerCoreLibrary('Ember Data', VERSION);
 }
 
 export default DS;

packages/-ember-data/addon/-private/system/debug/debug-adapter.js

@@ -1,5 +1,5 @@
 /**
-  @module ember-data
+  @module @ember-data/debug
 */
 import { addObserver, removeObserver } from '@ember/object/observers';
 
@@ -10,11 +10,12 @@ import { assert } from '@ember/debug';
 import { get } from '@ember/object';
 import Model from '@ember-data/model';
 
-/*
-  Extend `Ember.DataAdapter` with ED specific code.
+/**
+  Implements `@ember/debug/data-adapter` with for EmberData
+  integration with the ember-inspector.
 
   @class DebugAdapter
-  @extends Ember.DataAdapter
+  @extends DataAdapter
   @private
 */
 export default DataAdapter.extend({
@@ -26,6 +27,13 @@ export default DataAdapter.extend({
     ];
   },
 
+  /**
+    Detect whether a class is a Model
+    @public
+    @method detect
+    @param {Model} typeClass
+    @return {Boolean} Whether the typeClass is a Model class or not
+  */
   detect(typeClass) {
     return typeClass !== Model && Model.detect(typeClass);
   },
@@ -38,6 +46,15 @@ export default DataAdapter.extend({
     );
   },
 
+  /**
+    Get the columns for a given model type
+    @public
+    @method columnsForType
+    @param {Model} typeClass
+    @return {Array} An array of columns of the following format:
+     name: {String} The name of the column
+     desc: {String} Humanized description (what would show in a table column name)
+  */
   columnsForType(typeClass) {
     let columns = [
       {
@@ -57,6 +74,16 @@ export default DataAdapter.extend({
     return columns;
   },
 
+  /**
+    Fetches all loaded records for a given type
+    @public
+    @method getRecords
+    @param {Model} modelClass of the record
+    @param {String} modelName of the record
+    @return {Array} An array of Model records
+     This array will be observed for changes,
+     so it should update when new records are added/removed
+  */
   getRecords(modelClass, modelName) {
     if (arguments.length < 2) {
       // Legacy Ember.js < 1.13 support
@@ -72,6 +99,14 @@ export default DataAdapter.extend({
     return this.get('store').peekAll(modelName);
   },
 
+  /**
+    Gets the values for each column
+    This is the attribute values for a given record
+    @public
+    @method getRecordColumnValues
+    @param {Model} record to get values from
+    @return {Object} Keys should match column names defined by the model type
+  */
   getRecordColumnValues(record) {
     let count = 0;
     let columnValues = { id: get(record, 'id') };
@@ -85,6 +120,13 @@ export default DataAdapter.extend({
     return columnValues;
   },
 
+  /**
+    Returns keywords to match when searching records
+    @public
+    @method getRecordKeywords
+    @param {Model} record
+    @return {Array} Relevant keywords for search based on the record's attribute values
+  */
   getRecordKeywords(record) {
     let keywords = [];
     let keys = A(['id']);
@@ -93,6 +135,14 @@ export default DataAdapter.extend({
     return keywords;
   },
 
+  /**
+    Returns the values of filters defined by `getFilters`
+    These reflect the state of the record
+    @public
+    @method getRecordFilterValues
+    @param {Model} record
+    @return {Object} The record state filter values
+  */
   getRecordFilterValues(record) {
     return {
       isNew: record.get('isNew'),
@@ -101,6 +151,14 @@ export default DataAdapter.extend({
     };
   },
 
+  /**
+    Returns a color that represents the record's state
+    @public
+    @method getRecordColor
+    @param {Model} record
+    @return {String} The record color
+      Possible options: black, blue, green
+  */
   getRecordColor(record) {
     let color = 'black';
     if (record.get('isNew')) {
@@ -111,6 +169,15 @@ export default DataAdapter.extend({
     return color;
   },
 
+  /**
+    Observes all relevant properties and re-sends the wrapped record
+    when a change occurs
+    @public
+    @method observerRecord
+    @param {Model} record
+    @param {Function} recordUpdated Callback used to notify changes
+    @return {Function} The function to call to remove all observers
+  */
   observeRecord(record, recordUpdated) {
     let releaseMethods = A();
     let keysToObserve = A(['id', 'isNew', 'hasDirtyAttributes']);

packages/-ember-data/addon/index.js

@@ -1,12 +1,6 @@
 import { VERSION } from '@ember/version';
 import EmberError from '@ember/error';
 
-/**
-  Ember Data
-  @module ember-data
-  @main ember-data
-*/
-
 if (VERSION.match(/^1\.([0-9]|1[0-2])\./)) {
   throw new EmberError(
     'Ember Data requires at least Ember 1.13.0, but you have ' +

packages/-ember-data/addon/relationships.js

@@ -1,4 +1 @@
-/**
-  @module ember-data
-*/
 export { belongsTo, hasMany } from '@ember-data/model';

packages/-ember-data/app/initializers/ember-data.js

@@ -2,44 +2,11 @@ import setupContainer from 'ember-data/setup-container';
 import 'ember-data';
 
 /*
+  This code initializes EmberData in an Ember application.
 
-  This code initializes Ember-Data onto an Ember application.
-
-  If an Ember.js developer defines a subclass of DS.Store on their application,
-  as `App.StoreService` (or via a module system that resolves to `service:store`)
-  this code will automatically instantiate it and make it available on the
-  router.
-
-  Additionally, after an application's controllers have been injected, they will
-  each have the store made available to them.
-
-  For example, imagine an Ember.js application with the following classes:
-
-  ```app/services/store.js
-  import DS from 'ember-data';
-
-  export default DS.Store.extend({
-    adapter: 'custom'
-  });
-  ```
-
-  ```app/controllers/posts.js
-  import { Controller } from '@ember/controller';
-
-  export default Controller.extend({
-    // ...
-  });
-
-  When the application is initialized, `ApplicationStore` will automatically be
-  instantiated, and the instance of `PostsController` will have its `store`
-  property set to that instance.
-
-  Note that this code will only be run if the `ember-application` package is
-  loaded. If Ember Data is being used in an environment other than a
-  typical application (e.g., node.js where only `ember-runtime` is available),
-  this code will be ignored.
+  It ensures that the `store` service is automatically injected
+  as the `store` property on all routes and controllers.
 */
-
 export default {
   name: 'ember-data',
   initialize: setupContainer,

packages/-ember-data/tests/integration/relationships/belongs-to-test.js

@@ -1033,7 +1033,7 @@ module('integration/relationship/belongs_to Belongs-To Relationships', function(
 
     assert.expectAssertion(() => {
       message.get('user');
-    }, /You looked up the 'user' relationship on a 'message' with id 1 but some of the associated records were not loaded. Either make sure they are all loaded together with the parent record, or specify that the relationship is async \(`DS.belongsTo\({ async: true }\)`\)/);
+    }, /You looked up the 'user' relationship on a 'message' with id 1 but some of the associated records were not loaded. Either make sure they are all loaded together with the parent record, or specify that the relationship is async \(`belongsTo\({ async: true }\)`\)/);
   });
 
   test('Rollbacking attributes for a deleted record restores implicit relationship - async', function(assert) {