Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Test for API docs coverage changes #16910

Merged
merged 8 commits into from
Oct 14, 2018
Merged

Test for API docs coverage changes #16910

merged 8 commits into from
Oct 14, 2018

Conversation

ef4
Copy link
Contributor

@ef4 ef4 commented Aug 24, 2018

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
Copy link
Contributor

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
Copy link
Contributor

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

@jenweber
Copy link
Contributor

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

@ef4
Copy link
Contributor Author

ef4 commented Sep 19, 2018

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
Copy link
Contributor

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?

ef4 and others added 8 commits October 14, 2018 11:23
This adds a new test to the code-quality suite that ensure 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.
Taking better messages from PR 16912.
@ef4 ef4 merged commit 37403e8 into master Oct 14, 2018
@ef4 ef4 deleted the docs-coverage branch October 14, 2018 14:44
@jenweber
Copy link
Contributor

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

tylerturdenpants added a commit to emberjs/website that referenced this pull request Oct 19, 2018
Ideas, feel free to add to list or claim:
- [ ] ```I've been getting a lot of questions about how tree-shaking is coming along. I would be willing to train anyone that wants to help on what's already done and what still needs to be done. Disclaimer: It's a lot of work! #emberjs #EmberFest``` https://twitter.com/kellyselden/status/1050717338595745792
- [ ] Include summary from pixelhandler (and cc him) #issue-triage team: https://discordapp.com/channels/480462759797063690/480523776845414412/500377829452546058
- [x] From jenweber on #support-ember-times: Another times topic: emberjs/ember.js#16910 I would summarize as, "ember.js has an addition to the test suite to help with API documentation! In the past, you might have noticed that a small number of methods  had missing docs. When code gets moved around in ember.js, such as putting functions in their own modules, it's easy to make mistakes that impact the documentation parser. This test builds the docs and checks them for unintentional changes. Thanks <link to ed> for the test and to everyone who helped fix missing docs over the years." Todd Jordan did the majority of the fixes when things got dropped, I think. Hard to say for sure 🔏 @kennethlarsen 
- [x] emberjs/rfcs#384 (:lock: @jessica-jordan)
- [x] emberjs/rfcs#386 (:lock: @jessica-jordan)
- [ ] emberjs/rfcs#387 (:lock: @jessica-jordan)
- [x] emberjs/rfcs#388 (:lock: @Alonski)
- [ ] emberjs/rfcs#389
- [x] EmberConf brainstorming session date, if confirmed (:lock: @amyrlam)
- [ ] Hacktoberfest roundup?
- [ ] Check https://github.com/jessica-jordan/whats-new-in-emberland
- [x] [ember-self-focused](https://engineering.linkedin.com/blog/2018/10/making-ember-applications--ui-transitions-screen-reader-friendly) (🔒 @chrisrng )
- [ ] ...

Ideas we are waiting on:
- [ ] EmberCamp talks, deep dive? http://embercamp.com/ and https://github.com/ember-chicago/ember-camp-2018-notes ... Maybe we wait for the talk videos to be published? Keep an eye on #ember-camp in Discord. not out yet
- [ ] GraphQL with Ember? https://emberfest.eu/schedule/#rocky-neurock Or maybe we can reach out to them for a post-EmberFest writeup? See also the blog post: https://medium.com/kloeckner-i/ember-and-graphql-8aa15f7a2554
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants