IDE Minutes 2008-02-28
- Kevin Hakman, Aptana
- Lori Hylan-Cho, Adobe
- Stew Nickolas, IBM
- Ted Thibodeau, OpenLink
- Phil Berkland, IBM
- Ingo Muschenetz, Aptana
- Bertrand Le Roy, Microsoft
- Rich Thompson, IBM
- Kris Zyp, Sitepen
Kevin asks Jon to summarize where we are.
Jon responds: Completed our review of the JSON Schema comparison matrix. Side effects: completed first-past review of the property element, which is used in both the widgets and the JSAPIs. A question came up in e-mail relative to the scope attribute, but that's the only open issue aside from the ones pending a comprehensive API proposal from the Gadgets task force.
Gadgets task force had a discussion yesterday about the JSAPI; that's one direction we could go in next. Widgets and Gadgets are two others.
The property element discussion probably covers only 20% of the Gadget API proposal.
Kevin is most inclined to continue down the API path and flesh that out. [consent all around]
[Kevin encourages Kris to stick around and give us the toolkit perspective to help balance the IDE views.]
Turning to the API metadata...
Get agreement on how the overall markup should look Start with Aptana proposal and give thumbs up/thumbs down on different features of the proposal
Outermost node <api>? Thumbs up.
<property> is parallel/overlaps with <property> in widget metadata, as expected; we should keep an eye out for any places where they differ (or should differ).
Ingo: how to we represent multiple return-types?
Jon: That was an open issue, although I don't think we need multiple return-types.
Ingo: There's an edge case where we need a description for certain return-types.
Jon: We really only need to have one, since "list" is allowed. The suggestion is that there's a return-type attribute rather than a return-type tag, and that it could hold a list.
Jon: It could be an attribute on the <method> tag -- returns.
Ingo: Where would the description go?
Jon: That's why you'd want to have a subelement rather than an attribute.
Jon's going to send an e-mail to follow up on this to make sure we're all on the same page.
Jon: Let's talk about "class". I want to spend at at least one minute agreeing that we need a class element, and that properties, methods, etc. are subelements of class.
Bertrand: You might have methods and properties *outside* of a class.
Jon: Right. Aptana allows for that, right?
Ingo: Internally, we stick these in the "global" or "window" class.
Kevin: What's here is great when you have a class container, but how does someone who wants to describe a global method or property know what the different tools would consider the global class?
Phil: I guess the funciton object can have a property.
Ingo: Doing this class, method, property structure is very standard, but there are richer structures that we're probably ignoring.
Kevin: So this handles the sweet-spot middle...
Lori: Could we have a <global> element that's parallel with <class>?
Phil: If we had a class with name="global" when you combine toolkits, but that's not a problem as much if we have a <global> element.
Ingo and Kevin like this idea. Makes the xsd more complicated, but from an end-user perspective, it's simpler.
Ingo: We also need to discuss the concept of aliases. A developer might define all these functions in namespaces, and then "export" the functions into the global namespace so they're easier to access with less typing.
Kevin: There's greater chance of collisions in this case; they're convenient, but...
Ingo: We're doing something like this with Adobe AIR, where there are long namespaces functions like window.blah.foo.bar.borg, and you can access these with AIR.borg, etc.
Jon: How do we deal with the dynamic aliasing that's happening in the user community?
Ingo: That's almost like setting up your programming configuration. Discussion of how jQuery handles this ($j, etc.)
Jon: So the aliases would only be static, standard aliases.
Bertrand: I would like to point out that the IDE isn't the only client for this data. Programs that generate documentation, for example, will also consume this data, and they won't be able to figure out these types of relationships. We should have as much information as possible in the metadata, therefore.
Kevin: I think this argues for having an <alias> node. I think we should put the <alias> node back into the API metadata; it'll be refined further as we get to the implementation stage.
Jon: One of the other things that's in the Aptana spec but not in this example is <availability>. Let's ask Ingo what it does, what it's for...
Ingo: It's mostly to document for end-users what specification this implementation referenced.
Jon: So it's just informative.
Ingo: Yes. It's like, this is available in JScript, this is in JS1.2, etc.
Kevin: So I think this kind of information goes in the Description note.
Ingo: As for <browsers>, that's where we specify which particular browsers this thing works on. It was meant to be inclusive or exclusive; you could specify that it works on these three browsers, or that it does NOT work on this browser. It's also inherited, so it doesn't have to be duplicated. It's descriptive information, but we broke it out because we use it in Content Assist.
Bertrand: If we want to include this element in our proposal, I think exclusive should be the default.
Jon and Phil disagree; what if a new browser comes out?
Bertrand: But being inclusive has the same problem; what if you say you support Firefox, and a new version of FF comes out, and it breaks?
Bertrand: Maybe you can mark your whole library as supporting specific browsers, and then mark specific methods/properties that are exceptions.
Jon: OK, so we have a <browsers> element, and a <browser> element, and there could be an attribute for includes or excludes. But does anyone have a proposal for what this should look like?
Bertrand: We could probably come up with one for next time.
Ingo: Should we call it <browser> or <user-agent>?
Jon: I think <user-agent>