817827 - Hide (really) internal APIs from documentation

Status: RESOLVED WONTFIX

(Add-on SDK Graveyard :: Documentation, defect, P3)

Description

[Janet Swisher]

This is the Add-on SDK's module loader:
https://addons.mozilla.org/en-US/developers/docs/sdk/1.11/packages/api-utils/cuddlefish.html

Comment 1

[Will Bamberg [:wbamberg]]

It's not very clear, and cuddlefish should be documented too, but if it helps: cuddlefish is just an SDK-specific instantiation of the generic module loader, which is documented much more fully: https://addons.mozilla.org/en-US/developers/docs/sdk/latest/packages/api-utils/loader.html.

Comment 2

[Wes Kocher (:KWierso) (Not reading bugmail; email directly if needed)]

It might make more sense to just hide from the documentation pages the really-truly internal APIs that no one should be using.

Comment 3

[Will Bamberg [:wbamberg]]

Is there a list of really-truly internal APIs?

The simplest way to do this is just to remove the MD files, and rely on in-source comments for such modules. If that's good enough, and we have a list of really-truly internal APIs, and I'll delete the MD files.

If there is some purpose for having MD files but then not displaying them in the docs (and I can't imagine what that might be), then an alternative would be to have a module metadata key like "really-truly-internal", and it would be simple for the docs system to read it and not include the corresponding documentation.

Comment 4

[Dave Townsend [:mossop]]

I can imagine it being nice to have docs for people explicitly working on the SDK that are better than just source comments.

Comment 5

[Will Bamberg [:wbamberg]]

OK, so are we basically talking about another category of docs, beneath "High-level" and "Low-level", called "Internal" or something: so the docs are exposed in the browser, just in a different category, and with a top-level index file that explains that they are for people hacking on the SDK?

I think this is potentially a good idea, depending on how many modules fall into that category. As I say, we'd want a way to tell the doc code which modules fall into this category: metadata is the most obvious route although it might not be the best. With that done, it's easy to implement.

(I'm not very keen on actually hiding stuff in the docs browser: I don't think it's very helpful to anyone. It's better to show everything, but explain who it's for.)

Comment 6

[Dave Townsend [:mossop]]

Ok, are there any modules we currently have that it makes sense to hide from the normal docs pages? I'm not really seeing any.

Comment 7

[Will Bamberg [:wbamberg]]

Please ping me when you triage this.

Comment 8

[Gregg Lind (Fx Strategy and Insights - Shield - Heartbeat )]

Related work at https://github.com/mozilla/addon-sdk/pull/777

Prelim list of undoc'd modules:  https://gist.github.com/gregglind/4742742

Comment 9

[Will Bamberg [:wbamberg]]

Just to capture what we discussed in triage:

If there is a significant number of modules which are "really internal"[1], then it would be worth splitting them out of the "Low-level modules" group and displaying them in a separate section of the sidebar. The purpose of this is to make the list of low-level modules less huge, so it's easier to find interesting modules in there.

If we do this, we would need a way to indicate to the docs system that they are "really internal", probably using metadata, unless anyone has a better idea about that.

We don't want to *hide* any documentation.

Irakli will have a think about which modules might count as "really internal", and if there are enough, we'll go ahead. If there are only a few, it's not worth it.

[1] in the sense that they are only really of interest to people implementing specific SDK modules, and don't have a general application. For example, "core/heritage" is low level but generally useful, while "keyboard/utils" might only be of interest to people maintaining the "hotkeys" module.

Comment 10

[Irakli Gozalishvili [:irakli] [:gozala] [@gozala]]

I don't think this is still relevant given we're on MDN, so I'm clearing my needinfo. If you disagree let's start over again.