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

Meta: missing docs in the API viewer from 3.3 -> 3.4 #16993

Closed
jenweber opened this issue Sep 20, 2018 · 3 comments
Closed

Meta: missing docs in the API viewer from 3.3 -> 3.4 #16993

jenweber opened this issue Sep 20, 2018 · 3 comments

Comments

@jenweber
Copy link
Contributor

jenweber commented Sep 20, 2018

If anyone would like to help with a very important bugfix, there is a list of documentation that was dropped between Ember 3.3 and 3.4, in terms of what is rendered by the API docs viewer: #16910 (comment)

We lost the following public APIs:
"debugger"
"deleteMeta"
"descriptorFor"
"getOwner"
"partial"
"setOwner"
"with"
"yield"

I, for one, am super duper pleased that we can catch this kinda stuff moving forward using tests!

Missing docs are caused by one or multiple of the following:

  • public static methods that are missing an @static (public meaning that you don't have to instantiate a class to use the method)
  • a missing @public tag
  • they are in a file that has no @class declaration in it
  • they are in a directory that is not indexed by YUIdoc (configured here)
  • they got moved to the wrong module
  • generally incorrectly formatted yuidoc code comments

I think the action items here are, figure out why each got dropped, open a PR that fixes it and explains why it was being omitted.

It's a little bit tricky to get the hang of, but I think more people than me, Todd, and locks should be in the know about how it works, so if anyone wants to at least attempt detective work, that would be awesome.

You can see the basic yuidoc generated output by doing yuidoc . from the root of the ember.js repo and looking at docs/data.json. If a method doesn't show up somewhere in there, it has no chance of showing up in the API docs viewer. If it does show up there but still doesn't show up on the website, that's very possible because our website assumes a certain structure and hierarchy.

@jenweber jenweber changed the title Missing docs in the API viewer from 3.3 -> 3.4 Meta: Missing docs in the API viewer from 3.3 -> 3.4 Sep 20, 2018
@jenweber jenweber changed the title Meta: Missing docs in the API viewer from 3.3 -> 3.4 Meta: missing docs in the API viewer from 3.3 -> 3.4 Sep 20, 2018
@Gaurav0
Copy link
Contributor

Gaurav0 commented Sep 25, 2018

"deleteMeta" and "descriptorFor" are marked private in source and aren't listed in ember-rfc176-data. I'm therefore not sure if these are public apis. If someone can confirm they are public, I can mark them appropriately and they should be given RFC176 imports.

@jelhan
Copy link
Contributor

jelhan commented Sep 29, 2018

Not quite sure if this is important, but at least yield and with are missing in Class Ember.Templates.helpers docs since 3.2.

@locks
Copy link
Contributor

locks commented Mar 26, 2019

I think this is currently addressed.

@locks locks closed this as completed Mar 26, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

5 participants