Proposal: clean GroupData

MDN
#1

In the course of the event refactoring I’ve been doing some work on GroupData. This is the first time I’ve really dug into this data, and I’m quite dismayed at how out of date it is.

There are I think 136 APIs listed in GroupData. As far as I can tell, 53 of them, (almost 40%), should just be removed from the file. I’ve listed them below, along with an annotation of why we should remove them. “no docs” means I couldn’t find any docs for the API anywhere.

Alarm API                          FxOS, archived
Application Compatibility Layer    FxOS, no docs
App Cache *                        Obsolete
Apps                               Marketplace, archived
Audio Channels API *               FxOS, archived
Archive API                        ? no docs
Battery API *                      Obsolete
Bluetooth API (Firefox OS)         FxOS, archived
Browser API *                      Obsolete, no support
Camera API                         FxOS, archived
Contacts API *                     FxOS, archived
Data Store API                     FxOS, archived
Device Storage API *               FxOS, archived
Directory Upload API               ? no docs
Download API                       ? no docs
DOM (Non-standard)                 Obsolete, archived
Engineering Mode API *              ? no docs
Firefox OS                         FxOS, archived
FMRadio API *                      FxOS, archived
HTML Microdata API                 Obsolete, should be archived?
HTML Undo Manager API              Not implemented or documented
Identity                           BrowserID, archived
Idle API                           FxOS, archived
Input Port API                     ? no docs, FxOS?
Inter-App Connection API           ? no docs
Kill Switch API                    ? no docs
L10N API                           FxOS, archived
Mobile Connection API *            FxOS, archived
Mobile Messaging API *             FxOS, archived
Mozilla Payment API                ? no docs
MSISDN Verification API            ? no docs
Network Stats API                  FxOS, archived
NFC API                            FxOS, archived
Permissions API (Firefox OS)       FxOS, archived
Power Management API               FxOS, archived
Request Sync API                   ? no docs
Resource Statistics API            FxOS, archived
Settings API *                     FxOS, archived
Simple Push API *                  Obsolete, archived
Social API                         Archived
Speaker Manager API *              ? no docs
System Update API                  ? no docs
TCP Socket API *                   FxOS, archived
Time and Clock API *               FxOS, archived
TV API                             ? no docs
UDP Socket API                     ? no docs
Voicemail API                      FxOS, archived
Wake Lock API                      FxOS, archived
Web Activities                     FxOS, archived
Web Manifest *                     ? no docs
Web Telephony API *                FxOS, archived
WiFi Information API *             FxOS, archived
WiFi P2P API *                     FxOS, archived

APIs with “*” next to them are slated for removal already, in https://github.com/mdn/kumascript/pull/1136.

This isn’t just a theoretical thing: all the APIs in GroupData are listed in https://developer.mozilla.org/en-US/docs/Web/API, which is I think a fairly high-traffic page. It’s not a very good page, but it’s made much worse by the fact that we list almost twice as many APIs as we should, and that if someone clicks one of these links, there’s an almost 50% chance they will land on a page like https://developer.mozilla.org/en-US/docs/Archive/B2G_OS/API/Alarm_API, which is surely not a good experience.

To be clear, I’m not at this point proposing to delete any docs. Just to remove these entries from GroupData.

Obviously it’s entirely possible I’ve made some mistakes and am proposing the removal of some super-important APIs, in which case that would be good to know.

2 Likes
#2

Well, the Browser API will end up being exposed to WebExtensions (presumably once OOP <iframes> are better supported)

Also, I’ve been trying to hide these from {{ListGroups}} by checking if the target page is a redirect and allowing the guide‑like object for the overview entry.

#3

But that has nothing to do with Web/API, or GroupData. If it’s made available in WebExtensions, that will be documented under Mozilla/Addons, which doesn’t use GroupData.

Also, I’ve been trying to hide these from {{ListGroups}} by checking if the&nbsp:target page is a redirect and allowing the guide‑like object for the overview entry.

We could add various heuristics to ListGroups to try to improve things (one that I was also going to suggest, that’s complementary to this proposal, is not adding links where the overview file doesn’t exist), but it seems better to clean the data.

1 Like
#4

Of course, some of those have no docs just because we haven’t gotten to them, not because they’re not relevant. We need to figure out which those are and perhaps create issues on GitHub for them.

  • The Directory Upload API is actually implemented in at least Chrome and Firefox. I just checked.
  • The HTML Microdata API has been integrated directly into the HTML specification, so its stuff exists but isn’t separate anymore
  • Battery Status API is not obsolete; Firefox removed it because of privacy concerns but it is still a “live” API and is enabled by default in Chrome to this date

I would like to see an ability to list groups in various ways — all of them in one batch, or list a single category of them (media, core DOM, HTML DOM, etc), or al of them divided up by category.

1 Like
#5

some of those have no docs just because we haven’t gotten to them, not because they’re not relevant. We need to figure out which those are and perhaps create issues on GitHub for them.

Is there any concrete reason to include groups for APIs which we haven’t documented? Otherwise I’d recommend that we should remove them now, and add them back in when we have docs.

The Directory Upload API is actually implemented in at least Chrome and Firefox. I just checked.

Are you referring to this: https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/webkitdirectory , or something else? That’s the only thing I can see in our docs that seems connected to it, but the spec that links to is https://wicg.github.io/entries-api/#dom-htmlinputelement-webkitdirectory, which implies that this should be part of the “File System API” group, and not its own thing.

The HTML Microdata API has been integrated directly into the HTML specification, so its stuff exists but isn’t separate anymore

It seems like we should remove the GroupData entry, then, if it’s not a separate API?

Battery Status API is not obsolete; Firefox removed it because of privacy concerns but it is still a “live” API and is enabled by default in Chrome to this date

Then our docs (including BCD) are consistently wrong.

#6

Depends on precisely how you define “concrete.” I was not aware that GroupData was meant to be dependent on the current state of our documentation; I thought it was supposed to define the set of Web APIs independently of MDN’s content. Especially since the data gets used for things other than simply generating doc content on MDN. We need to think more broadly than our own site needs when dealing with these things.

I’m not referring to any existing documentation. We have not yet documented the Directory Upload API, at least not in any meaningful way. But Firefox at least partially implements, for instance, the Directory interface, which is part of that API, and Chrome’s API status pages indicate support for it. This API does not yet have a formal specification, however. The only spec available is currently this: https://wicg.github.io/directory-upload/proposal.html.

Agreed. It’s just not obsolete. This actually makes me wonder – would it make sense to add something to GroupData that would let us redirect specifications? I ask because if someone is in fact using this data set for something, it could be helpful to be able to indicate “this has been merged into that”. Just a thought.

Yes. They apparently are.

1 Like
#7

Can you show me where GroupData is used outside MDN? What are the specific requirements of these projects?

It’s a KumaScript macro, so it’s hard to imagine it being used outside KumaScript.

Inside KumaScript, I used https://github.com/mdn/kumascript/search?q=GroupData&unscoped_q=GroupData as an initial indicator of where it is used.

The only references here that aren’t test code or false positives are:

As far as I can tell the first three of these wouldn’t be affected at all by removing groups that don’t have any docs, since if there are no docs, there are no sidebars or interface overview pages.

The effect on the fourth would be that obsolete and archived docs wouldn’t be listed on the Web/API and Web/Guide/API pages, which seems like a good thing.

#8

I’ve filed https://github.com/mdn/kumascript/pull/1149 for this.