Quick review of System Info

Hi,

here are some notes on System Info.

• The abstract should be more descriptive, as if it were final (not a "proposal")

• The SotD needs to have one custom paragraph. You can get it with:

<section id='sotd'>
  <p>
    blah blah blah
  </p>
</section>

• It would be good to have those Security considerations fleshed out :) Is there a chance that they may be different depending on the section?

• A Conformance section is needed, identifying at least one product class.

• References appear as [FOO] but should be written [[FOO]] or [[!FOO]] if you want them linked and added.

• When discussing an interface in prose, it is better not to use <code>Dahut</code> but rather <a>Dahut</a> if it's defined in the same document — that way it'll get linked automatically.

• There are a few "successCallback", we've more or less agreed to go with "successCB" to avoid long lines.

• Is it really necessary to have "optional Foo? foo"? I would assume that if something is optional and you pass null, it means you're not passing it; but if it's marked as nullable that means that you've passed it and it's null. I'm not sure it makes a difference to implementations, but we should agree about the right way across specs here.

• "When called, the function MUST immediately return and..." This isn't really a testable assertion, it should be "When called, the function immediately returns and...". If you want to make it a TA, it should be "the user agent MUST immediately return" but the "immediately" isn't something one can happily test. I think that just the descriptive text is enough.

• There is a number of other cases where it says "this method MUST invoke" or similar things. In general if you have a TA and the sentence doesn't mention a product class (probably the "user agent") then something is fishy. Dom has been drafting text about this which we should all read once it's found a home.

• If you include the class sh_javascript as part of your JS examples, you'll get free syntax highlighting.

• Using CURIEs is interesting, but it warrants some introductory discussion. Do we really need to reference CURIEs? In the absence of a mechanism to declare one's prefixes, it doesn't seem to help much. We might just as well define our own short names and tell others that if they want to extend the API they have to use URIs (or vendor-prefixed names).

• The order of parameters that is used is successCB, errorCB, options. Is it likely that options will be used more often than errorCB? If so they should be before it.

• "Type of returned value: PowerState" It's not really a returned value since it's provided through an async call. Simply "Value type:"?

• Power: is there value in exposing the system's "warning level" (the point at which it tells the user that things will go wrong soon)? Or is that zero? Note that "a value of 0 means that the battery level is lowest before the system stops": what do I get if I've removed the battery but am plugged in?

• CPU: is it much of a hassle to expose multiple CPUs right now? If I have an app that can only use a single CPU, it might be maxing out but the system might still report "using 52%" because the other one's idle. It seems like an array of values wouldn't hurt here (and a requirement that they are always in the same order).

• Thermometer: "A value of 0.0 means that the system is running at the lowest safe temperature, and a value of 1.0 means that the system is running at the highest safe temparature." Is this typical of thermometer APIs? I was more expecting something in C° (or K°), possibly alongside an indication of whether the system thinks it's unsafe. Should this just use Thermal? It seems that that's what INTERNAL_COMPONENT is for.

• Also: "On devices that have multiple thermometers, this value should reflect the average temperature of all the thermometers." That's really not very useful :) My battery's thermometer might be indicating that it's close to exploding, but the DVD's might be just getting some residual heat. Again, this seems like an array would be more useful, especially if it's to warn me that something's going to go toast.

• Averaging cooling fans: similar issue.

• Display: I'd recommend fully specifying what window.screen does in browsers, adding the desired extensions, and making that the spec for it (even if we have to split it out). It seems useful, and to the best of my knowledge no one else is doing it.

• Also Display: the various watch* return an int, and clearWatch() can clear it. This is in line with setTimeout, but not with the (I think) friendlier PendingOp that we have for the newer stuff. Is there a reason for not doing this the same way as PendingOp? Or even just reusing PendingOp? The same comment applies to other interfaces.

• DisplayOrientation: are we being short-sighted in only listing four? Would it make sense to have it be an angle, except that in most cases it would only change in 90° increments?

• isReachable: what does it mean for a URI to be reachable? For instance, I ask if http://berjon.com/ is reachable, the IP stack connects correctly but the HTTP layer doesn't answer — is it reachable? What if I get a 404? A 5xx? The URI parameter is also underspecified — is it an IRI? What are those non-terminals that are referred to but not defined? It doesn't seem like a good idea that this would be synchronous. I'd suggest making this work only at the IP layer (just IP/DNS plus port) and let other parts of the toolset (XHR, WebSockets, etc.) handle determining if higher layers are "reachable" or not, and what that means for the application. Same comments apply to its sibling methods.

• "NOTE: [DCONTOLOGY] has an additional operation band attribute that is associated with networkTechnology, but I have a difficult". This should be marked with class=note (and probably not use the first person; or otherwise use class=ednote which is being added).

• NetworkBearer: for a lot of the attributes there, it should be specified what the implementation says when a value isn't known (null, 0, etc.).

• sampleInterval (and similar options): it should also be clear that implementations are allowed to ignore values set at a threshold that they consider too low.

• PendingOp: you can now reference the Core Device spec for that.

• General point: I'm wondering if this specification shouldn't be split into a bunch of smaller specifications (which we can do) so that parts could be shipped independently from one another? This would prevent it from blocking if people don't want to implement some part even when there's strong interest in another.

--
Robin Berjon
  robineko — hired gun, higher standards
  http://robineko.com/

Received on Monday, 7 December 2009 17:34:32 UTC