Sorting through APIs using visibility

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.

[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).

[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.