Needed for 3.10 or 3.11 - Verify that Ember Data's API docs work correctly for the monorepo, and fix issues

[jenweber]

Description

The API docs site relies on a particular structure of YUIdoc code comments in order to work, and they have some peculiarities. We need to make sure that when the monorepo lands in a stable release, the API docs are working and no docs have been dropped.

To-do

• run yarn build:production against v.3.9.3 and v3.10.0-beta.1 tags. You'll find a docs.json file in docs/data.json and packages/-ember-data/dist/docs/data.json on those corresponding tags. Diff those files to see the changes in packages.
• fix any missing docs (note that all files must include a class declaration, some methods need an @static, and the file path must be included in the yuidoc config for something to show up)
• Once the yuidoc json is in good shape, try running it in the API docs app. See https://github.com/ember-learn/ember-jsonapi-docs and https://github.com/ember-learn/ember-api-docs
• Coordinate with the Ember Data team to make sure that the fixes to docs get included in the release (might have to be added to an existing beta)

Part of work for emberjs/rfc-tracking#11

[sivakumar-kailasam]

With #6153 we can view the latest docs on the API app. An open issue that we're aware of is the file's location shown for the defined in field on the api app. It needs to be handled by the api app.

[sivakumar-kailasam]

Also unsure if this is intentional but the api docs' content doesn't reflect the new npm packages. They still seem to be namespaced under DS.

[runspired]

@sivakumar-kailasam if we merge #6153 and release a beta, are we comfortable with packages becoming available in the 3.11 release?

[sivakumar-kailasam]

Without that PR, the docs won't be generated for 3.11 so it has to be merged.

Our concern was that the docs still don't reflect the new package restructuring that has happened. So it's possible that users maybe confused since they don't see any of the new packages in the docs.

If that's intentional, then we're probably okay.

[sivakumar-kailasam]

We've published 3.11 docs but there are couple of outstanding issues:

1. Links to source code is broken (this needs to be handled by the api app team. I'll be tracking it via Ember data 3.11 docs is broken ember-learn/ember-api-docs#625)
2. ember data API docs don't reflect the new package structure. This needs to be handled by the data team. If the existing classes are decorated with the modules that they belong to & if the references to DS. is replaced, things should show up as expected. ember-source repo is an excellent reference for this.

[Gaurav0]

@sivakumar-kailasam Is this fixed on the data side with the patch releases?

[sivakumar-kailasam]

It's partially fixed but there are still issues that need to be fixed which we're working on. In the meantime please refer to https://api.emberjs.com/ember-data/3.10 since the DS package still aliases the new packages' classes.

[runspired]

Leaving this open as long as there are still issues with the published docs although I believe our work in this library for this issue is complete.

[sivakumar-kailasam]

@runspired the 3.11 now shows the expected packages under each of the modules on the api app. the @ember-data/model package seems to be empty though(that seems to be the case even in the default yuidoc html file). If someone from the data fixes the jsdoc and publishes another patch version, that should fix that.

[Gaurav0]

@sivakumar-kailasam fixed blank @ember-data/model package in #6444

[sivakumar-kailasam]

Thanks @Gaurav0 🙇🏻‍♂️. This should resolve this issue