Re: Quick review of System Info

Hi Robin. Thanks for the comments. I've fixed most of them, although I 
should have made it clearer than anything below Internal was old and 
didn't require a review. Sorry for that. I've now added a marker that 
will move down as I progress.

Comments on some of your comments below.

On 07/12/2009 18:34, Robin Berjon wrote:

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

Possibly. But it's very likely that there will be a global section anyway.

> • 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.

But if they aren't they remain simple <a>'s that are links that don't 
point to anything and aren't visible as links. At least it would be nice 
if they looked like <code>


> • 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.

Indeed, I was wondering about it. Since I would like to allow:
get(property, success, null, options)
get(property, success)
get(property, success, error)
but not
get(property, success, null, null)

I suppose the right answer is
get(DOMString property, SuccessCB success, optional ErrorCB? error,
     optional options)

> • "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.

Agreed. I suspect that with the style of prose I'm using I would end up 
without any of the capitalised words, and I'm not that worried about it, 
tbh.

> • 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.

...until Dom's text is out.

> • 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).

Something I borrowed from Bondi. I think it is indeed interesting, but I 
must admit I haven't looked into it yet. But I will in an upcoming pass 
through the text.

> • 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.

I'm not sure about that, but I'll be happy to follow what others do.

> • 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?

I haven't seen many low-level system APIs expose warning levels, so I 
thought leaving the DAP developer define them through thresholds was better.
To answer your question: if the battery was removed and your were 
plugged in then the level would be 0 and the externalSource flag would 
be on. The prose isn't precise enough there, so I'll refine.

> • 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).

Following the 80/20 principle, I've not put multiple CPUs in because I 
doubt that more than 20% of users will care about multiple CPUs, GPUs 
and whatnot. However, I've left the door open by having the callback 
return a CpuState object rather than a single value. So you could expand 
the current type as:

interface CpuState {
   attribute float load; // global system load
   attribute SingleCpu cpus[];
}

interface SingleCpu {
   attribute float frequency;
   attribute DOMString info;
   attribute float maxFrequency;
}

I might be wrong, but I wouldn't put it in this version of the 
specification.

> • 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.

The reason why I just had a 0-1 value is that indeed you have devices 
with many temperature sensors, so indeed an average temperature doesn't 
make sense. (So I should have removed "average" and phrased my statement 
as "the value should reflect the general temperature state of the 
system".) And for the same reason as above, I think an array is not what 
most webapp/widget developers are going to want to bother going through.

> • 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.

 From an editorial or W3C process point of view it wouldn't be so great.
I might be wrong, but I really prefer to see a simple specification (at 
least for the first version) and I'm please that sections like battery 
are currently no longer than the height of my screen. Perhaps we just 
want to add some feature string. I know that they are controversial, but 
they're not any different from separate specifications.

Max.

Received on Tuesday, 8 December 2009 10:08:03 UTC