Hide quick access to private APIs

[sivakumar-kailasam]

On the left-hand side on TOC we need to show deprecated classes always without the need to enable the checkbox. The checkbox for Show Private/Deprecated needs to removed. We need to add a new query param that will let us show private classes/namespaces/modules which will be false/hidden by default (may be ?show-private-toc=true).

In addition we need to remove the private checkbox on the methods/properties index on right side. If someone needs to view private info, they can use the existing query param (?show=private) to do view it.

//@Kapeli - fyi

[toddjordan]

For the time being I'd like to hide the private checkbox in classes when the private checkbox in the left nav is unchecked. I think that will help some confusion. If we bring back api-internals, I think we can get rid of the private checkbox altogether for the main site.

For deprecated, I think we still need to show them, but should clearly mark them as deprecated to avoid new usage.

[sivakumar-kailasam]

these were @locks' inputs from slack, so i'll let him weigh in :)

[toddjordan]

I'm ok hiding it on the UI if they are still link accessible, but I'd like the leave the feature. Linking the private checkbox in class to the private in the left nav was an alternate suggestion that will still make things hidden unless you want it (especially if we get blowback)

Also, I do think we should leave deprecated regardless, just clearly label them. Most all api docs show deprecated things.

[Gaurav0]

Hi all, I recognize the need to hide private APIs and long deprecated APIs to new users. However, I don't think we want to make experienced users have to constantly ask in Slack how do I see private APIs now? Thanks,Gaurav

On Monday, July 24, 2017 12:40 PM, Todd Jordan <[email protected]> wrote:

I'm ok hiding it on the UI if they are still link accessible, but I'd like the leave the feature. Linking the private checkbox in class to the private in the left nav was an alternate suggestion that will still make things hidden unless you want it (especially if we get blowback)Also, I do think we should leave deprecated regardless, just clearly label them. Most all api docs show deprecated things.— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub, or mute the thread.

[locks]

@Gaurav0

However, I don't think we want to make experienced users have to constantly ask in Slack how do I see private APIs now?

We didn't remove private APIs (and moved them to /internal) from the previous documentation iteration by mistake :P I am also fine with experienced developers having to check the source code over beginner developers stumbling over API that will likely bite them in the future.

I think it was stated publicly before that if there is something that you want to accomplish with Ember and it can only be done through private APIs, we consider it something that should get addressed through the RFC process so we can empower the developer.

I hope I'm making sense with the above. We are also still working on restructuring how we're presenting the information, which will impact this.

---

@toddjordan

Also, I do think we should leave deprecated regardless, just clearly label them. Most all api docs show deprecated things.

Yes:

On the left-hand side on TOC we need to show deprecated classes always without the need to enable the checkbox.

[jaredgalanis]

@locks @sivakumar-kailasam Happy to help with this one.

[sivakumar-kailasam]

@jaredgalanis go for it 👍

[jenweber]

Here's the summary of what was discussed at the learning team meeting:

• Don’t show private classes at all in the sidebar table of contents
• DO show deprecated classes in the table of contents, and label them with an icon like an alert ! for example. Deprecated classes should always be shown without need to check the box at the bottom of the sidebar. Remove checkbox.
• Once a topic is selected, no private methods or properties at all should be shown. Checkbox for private should be removed

[Gaurav0]

@jenweber Thanks. We are still going to provide the query param as stated in this issue by @sivakumar-kailasam , right?

@locks :

We didn't remove private APIs (and moved them to /internal) from the previous documentation iteration by mistake :P

No. Please, let's keep this discussion civil and avoid sticking out our tongues. I had to raise quite a stink to stop them from being removed from the api docs altogether, and I hope we don't have to revisit that issue again.

[jenweber]

Hi @Gaurav0 , that's right, the query params ought to still be availble. These steps are to hide the UI checkboxes from the average user.