Sorting through APIs using visibility

[Oreoz]

I’ve been helping out on the docs website for ember-animated and we’ve ran into a use-case where we would like to enable the users to only see public APIs starting off and give them the opportunity to venture off into private / deprecated APIs later on when they really need to — in order to not overwhelm them starting off.

Here's what I cobbled up as a POC -- as you'll see it's heavily inspired by the Ember docs.

Sam mentioned a re-design of the docs website so I'll hold out on this, but I'd be happy to help it come to life when the time comes.

[ef4]

Thanks for tracking this. In my ideal design, the controls would clearly be global and would effect even what appears in the left sidebar, since whole classes could disappear.

[acorncom]

I'm assuming @ef4 is hoping for something akin to what exists right now at the bottom of the Ember api docs sidebar

[knownasilya]

You could even put the above 3 items behind a "cog" icon as a dropdown for the whole site. I'm sure other things will probably make it into there in the future.

[pzuraq]

This should be in the latest version of ec-addon-docs, are the filters there not what you’re after? Note that they’ll only show up if you actually have private/protected/deprecated values on the class

Edit: missed the global-ness of the filters, definitely like that idea for filtering private folders and classes 👍 it’ll require some changes to the sidebar, but I’m def on board.

[pzuraq]

So touching back on this, I'm thinking we should add a cog style dropdown like @knownasilya suggested in the sidebar near the API Documentation header, with two options for now:

• private
• deprecated

I'm personally in favor of automatically marking -private folders as private, and not providing granularity outside of that. Deprecation will require actual tagging no matter what, but at least this way we're guiding users toward a more normalized structure. I'd also like to add a debug flag in the future, targeting -debug folders (which are commonly used for code which is stripped in production).

[samselikoff]

Just thinking out loud, is there an argument for not showing anything private on the site? I know Yehuda mentioned to me once that he did not like that any private APIs were on the Emberjs site. I can kinda see that point.

[pzuraq]

I can see that point with the current state of things, but I think the downsides are really not as bad once we get true private fields and methods. Private things being private-but-documented currently leads to scope creep for "intimate APIs" - if people don't know about them, they can't use them 😛

I don't think there's a way to make anything a module exports truly private though, yet. This is why I would lean hard on "only things in -private/ folders are marked private", because then it really sends an unambiguously clear signal to users that this is private API and it may change/break at any time. That said, I definitely think it should be made configurable, and I'd be open to disallowing it entirely until we can figure out a way to make modules truly, fully private.