Of undocumented Chrome features and unreadable W3C specs

Today I rant about undocumented Chrome features and unreadable W3C specs. There’s too much of both nowadays, and I’m getting VERY tired of both. Google and W3C should clean up their act.

Today’s problem: window.webkitStorageInfo , which gives information about available and used storage space for localStorage and sessionStorage (and maybe more storage types, but I haven’t tested that yet).

Undocumented Chrome features

Although it’s Chrome-only, I wanted to incorporate this in my upcoming local/sessionStorage test suite since it gives important information. But how does it work?

Fortunately I found a developer.chrome article that gives a code example:

// Request storage usage and capacity left window.webkitStorageInfo.queryUsageAndQuota( webkitStorageInfo.TEMPORARY, //the type can be either TEMPORARY or PERSISTENT function(used, remaining) { console.log("Used quota: " + used + ", remaining quota: " + remaining); }, function(e) { console.log('Error', e); } );

Lo and behold, this works. Cool. Except for the niggling fact that the console gives this message:

'window.webkitStorageInfo' is deprecated. Please use 'navigator.webkitTemporaryStorage' or 'navigator.webkitPersistentStorage' instead.

Fair enough. Methods and properties evolve, and I’d like to test the most modern one. So I switched from window.webkitStorageInfo to navigator.webkitTemporaryStorage . And my script stopped working:

Uncaught TypeError: Failed to execute 'queryUsageAndQuota' on 'DeprecatedStorageQuota': The callback provided as parameter 1 is not a function.

So apparently the first argument must be a function. Which function? What is it supposed to do? Can I get a code example? No, apparently. I searched for queryUsageAndQuota and found ... nothing. No documentation, no code example. No way of figuring out what the first argument should be.

Related: it seems this entire API was removed from Web Workers, but kept in the main thread. I can’t judge the technical pros and cons, but I do know some sort of warning or note would have been useful.

Way to go, Chrome team.

Unreadable W3C specs

Now it was suggested that the correct way of doing this can be found in the specification. That’s entirely possible, but I am unable to make heads or tails of the spec. A translation to a human language would be mucho appreciated; even a simple code example would help a lot. But no, W3C doesn’t do code examples. IDL definitions are teh coolnez, and who cares if developers can’t read the specs they’re supposed to develop against?

Another example that irritates me: CSS Device Adaptation, which specifies the viewports, a topic near and dear to my heart. I think I can state that I’m one of the world’s leading experts on viewports, since I studied them since before anyone else figured out they were going to be important, and did so in ALL browsers, not just Chrome, Firefox and Safari.

But the spec could as well be written in Luwian as far as I’m concerned. I can’t even figure out if it describes the current state of viewports or some idealised future that we should all work towards.

Heads, tails, please report to me at your earliest convenience. I can’t make you of the spec. (And yes, that’s terrible syntax. Serves IDL well.)

Way to go, W3C.

Update: I wrote an article specifically about the problem I have with the Device Adaptation spec.

Three problems

It may be that I’m being an obtuse and stupid old fart (turning 45 this year), and that the solution is in fact fairly simple, but this example highlights three worrying trends that I see creep up too often in modern web development.

Cram your browser full, and I mean FULL, of exciting new stuff and subsequently refuse to document it. Oh, there are happy-happy-joy-joy introduction articles, and they have their place, but I need documentation: a list of methods and properties I should test, and a clue as to what they do and which arguments they expect and so on. I need those lists to make sure I don’t forget to test something important.

But Chrome sucks at documentation. I knew that already, but it’s biting me now. Write an exciting new spec that’s completely fucking unreadable due to all the IDLish W3-speak the authors need to impress other W3C authors. The only thing that’s needed is a simple code example, and I can take it from there. But it seems there’s no budget for code examples. (W? T? F?) Most web developers together, shouting at the top of their lungs: “But XXX is a brilliant tool that solves all this for you!”

Some web developers, also shouting: “No! Use YYY instead!”

Fuck tools. I don’t do tools. Besides, if no web dev can understand the specs any more and just uses tools ... do we want to go there?

Also, tool makers need compatibility info. Guess where they get it?

Anyway, this sad state of affairs prevents me from writing tests and reporting their outcome on all these new, exciting technologies. Chrome team, W3C, clean up your act. This is getting ridiculous.

Can’t we just stop cramming new stuff into browsers for a while? Give people a chance to catch up? And to document all this exciting new stuff in a human language instead of bloody IDL?

Thanks all for listening. I feel much better now.