IDE Minutes 2009 02-17
- Jon Ferraiolo, IBM
- Kin Blas, Adobe
- Lori Hylan-Cho, Aptana
- Javier Pedemonte, IBM
- Bertrand Le Roy, Microsoft
- Adam Peller, IBM
Jon: As we decided at the last phone call, I moved a few things out of the main spec into the Futures appendix.
Jon: I also added a new section in the appendix about things we might pursue in a future version.
Jon: Since the Gadgets TF is working in parallel with us, thought we should mention this.
JSON representation of OpenAjax Metadata
Adam: JSON is more natural. Might be a useful API to document down the road.
Kin: How do you handle multiple occurrences?
Adam: Still working things out. Sometimes arrays. Sometimes associative arrays if there is a key.
Jon: Two approaches. One extreme you make the JSON take into account every particular XML feature so that any XML grammar can be converted into JSON. Other extreme is to make as simple and direct a version of JSON for your particular infoset. Adam is doing the latter.
Jon: Any objections to adding this to the Futures appendix?
Inline API commenting conventions
Jon: There has been talk about getting into the JSDoc area, similar to what Aptana has done with their @ tags. Phil Berkland is likely to implement this something in the coming months. We talked about this at the Interop phone call yesterday. We are documenting Hub 1.1 APIs using JSDoc in conformance with JSDoc Toolkit.
Lori: No problem with a future might.
Jon: What I'm thinking as a good strategy down the road is to start with the JSDoc Toolkit and only make changes where we find things broken or missing. But that's just my thoughts. If we pursued this, we would have the committee develop it and make decisions. Not exclusive. Just here is one approach, and it maps to our XML format.
Jon: Any objections?
Jon: As before. No recent changes.
Jon: I converted lots of colored comments into text. I added a <Locale> element to provide the URL for where the message bundle files are located. This is in Google Gadgets, and we have copied everything else from there. Anyone disagree with adding it?
RESOLUTION: Add <Locale> element
Jon: Just realized there is no default value for the URI. One option is to use the W3C default, which is ./locales.
Kin: Relative to XML file or relative to root of the web server?
Jon: Relative to XML file
Kin: I agree
Jon: Need to see what Gadgets does by default
ACTION: Jon to research what Gadgets uses as a default for <Locale> URI
(discussion about what happens if 'lang' vs 'country' when 'lang' has a country value)
Jon: Now that I think about it, what we have done in the past is decide if the file is wrong, then the result is implementation-dependent
Message bundle processing algorithm
(long discussion about merge vs no merge. With merge, for each message, you search the first locale, if not found, then the next best locale, etc., down to the fallback. With no merge, you find the message bundle file and just use it. All localization strings must be in that file. The merge approach matches how localization is often organized, where the country-specific localizations are a small number of overrides versus the language-specific localizations; however, if localization files are on a server, you might have lots of HTTP requests and cause 404 errors, which makes server admins unhappy. If no merge, then each localization file has all of the strings, which is a negative when the message bundles are included inline and you have several message bundles. Discussion about how we could specify the merge approach, but encourage tools to do some sort of preprocessing to achieve optimal runtime behavior.)
ACTION: Jon to research whether Gadgets does merge or no merge (Gadgets does indeed support merge
RESOLUTION: Pending Jon's research, we will adopt the merge approach, and encourage implementers to optimize to that minimal runtime HTTP requests.
RESOLUTION: Move File substitution to Futures appendix
API Metadata examples added by Lori
Lori: I removed the note about compact rng
Jon: Good. That was an error. The example is perfect. Short and to the point.
Jon: I like the first example
Lori: That was the one you did previously
Jon: No wonder. OK, let's look at second example
Jon: Should check on copyright
Jon: Should we use jQuery for API examples and Dojo for widgets?
RESOLUTION: Use whatever toolkits have OpenAjax examples ready. We have jQuery examples for API metadata. That's good, lots of people know jQuery. For widgets, use combination of various toolkits. We have YUI and Dojo examples now.
Jon: What about <shortDescription>?
(discussion - shortdescription is different than title, so despite dislike for adding yet another element:)
RESOLUTION: Add <shortDescription>, say that if either <shortDescription> and <description> are missing, use the other one
(discussion about datatype="Options". We agreed in the past that this would be possible, but not in the spec. Jon needs to research)
ACTION Jon to research datatype options.
Lori: We decided to allow properties as children of parameters
Jon: Yes, I need to fix the spec
ACTION Jon to fix spec to allow properties as children of parameters
(discussion about datatype="Callback" - shouldn't that be datatype="Function"?)
Lori: Let's mark that example as suspicious