Test for API docs coverage changes

[ef4]

This adds a new test to the code-quality suite that ensures we are exporting the expected set of items into the API docs.

We have repeatedly lost parts of the API docs without noticing, so I believe this test is worth the extra friction for people who are intentionally adding or deleting public APIs.

The expected workflow is: if you just deleted a public API, you will get a lint error asking you to confirm that you really meant to by editing tests/docs/expected.js. And similarly if you add a new public API, you're asking to confirm so that we can catch the future deletion of your API.

[jenweber]

I think checking classitems might be sufficient. No simple test can catch everything, but this would catch the most likely mistakes.

I think it would be good to offer more specific directions regarding failures:

If you intended to add new documentation, please update tests/docs/expected.js. Note that public properties must be marked @public and @static for them to be included in the Ember API Docs viewer.

If you really intended to remove these from the API docs, update tests/docs/expected.js. If not, documentation is missing, the file with documentation lacks a class declaration, it is incorrectly formatted, or the file is in a directory that is not watched by yuidoc.

Particularly the @static is an annoying thing to have to remember.

[jenweber]

P.S. thank you for writing this! It will be a huge help.

[jenweber]

@ef4 is there anything else this needs before it’s ready for review/merge?

[ef4]

I reran CI just to make sure this is still good and several things disappeared from the docs since I authored it:

  "EXTEND_PROTOTYPES"
  "LOG_STACKTRACE_ON_DEPRECATION"
  "LOG_VERSION"
  "_APPLICATION_TEMPLATE_WRAPPER"
  "_JQUERY_INTEGRATION"
  "_TEMPLATE_ONLY_GLIMMER_COMPONENTS"
  "debugger"
  "deleteMeta"
  "descriptorFor"
  "getOwner"
  "partial"
  "setOwner"
  "with"
  "yield"

[jenweber]

That's unfortunate but also I'm so glad we can catch these now. Net result is super happy. What do you think we should do, fix the missing docs and then merge? Adjust the tests and merge, then fix the docs?

[jenweber]

Thank you for bringing this to the finish line! It will be such a huge help.