IDE Minutes 2009 01-20
- Jon Ferraiolo, IBM
- Kin Blas, Adobe
- Lori Hylan-Cho, Aptana
- Nitin Dahyabhai, IBM
- Bertrand Le Roy, Microsoft
Proposal: minor schema change to add <author>/<authors> to descriptive_elements
We have a long-standing red-colored note in the metadata spec that says: "JSDoc v2 allows @author on constructors, methods and properties. Shouldn't we allow it in our schema also so that JSDoc can be mapped into our format (even if few people will specify @author at such a fine level and even if tools will usually ignore this information)?" We haven't discussed this issue because we had more significant things to discuss, but let's try to make a decision on it at today's phone call. PROPOSAL: Right now, the schema defines 'descriptive_elements' as: descriptive_elements = ( description_element? & examples_element* & example_element* & remarks_element? & references_element* & reference_element* & title_element? ) My proposal is to add <author> and <authors>: descriptive_elements = ( authors_element* & author_element* & description_element? & examples_element* & example_element* & remarks_element? & references_element* & reference_element* & title_element? ) This change will address the JSDoc->OpenAjaxMetadata conversion issue. The main downside to this change is that <author>/<authors> will be legal in lots of places, but I don't see that as a big problem because generators don't have to put <author> elements on everything and consumers don't have to do anything with every <author> element in the file. Also, we have similar issues with other elements, such as <example>/<example>, which are available in lots of situations where they probably won't get used by industry.
Lori: Not a big one on our side
Kin: Same here
Is this paragraph for the <api> element OK?
Lori: I wouldn't expect two <api> elements to interact. Just one API metadata file for whole library and wouldn't interact.
Kin: Some libraries might want to separate based on component libraries.
Jon: Yes. Besides modularity within a library, there are also 3rd party extensions.
Jon: We have discussed this multiple times already and each time agreed that there could be multiple API metadata files and the tool would find them via recursive directory searches.
Lori: The part that worries me the most is "in order to resolve dependencies". Let's remove that.
Kin: Where are the metadata files? In the tree? Outside of the tree? Ask the user?
Jon: Up to IDE
Lori: We aren't searching. We are asking vendors to deliver it.
Jon: Kin's right. This should be a spec issue.
Kin: Shouldn't impose additional restrictions.
Jon: Or requirements
Kin: Leave directory structure out of it.
Kin: Are there ways to declare dependencies?
Jon: This spec is focused on code assist
Kin: Requires preloading?
Lori: That's what we are doing now
Jon: Could run through files and build an index of classes that are defined across all of the files
Kin: That's what I meant
RESOLUTION: Remove 5 words, remove references to directory trees, OK to use multiple API files
Another paragraph to review: 'datatype' for <ancestor>
Bertrand: Should be able to in general, but with some limitations in practice
RESOLUTION: Remove sentence that begins with "However"
<option> element: what happens if no label?
Right now in the Datatypes chapter, under the <option> element, there is a red-colored comment as follows: -------------------- 2008-09-12 what happens if no label? Default to the 'value'? -------------------- I will try to do some research before the phone call, but my memory is that we talked about this and decided that if there is no label, then use the value for the label.
Jon: Reminder that the displayable label content was made textual content to allow it to be localized
Lori: Yes, default to the value. Not all values will be localizable
RESOLUTION: label defaults to value
OK to remove blue-colored "Tentative resolutions" comments from spec?
I think it's time to push the OpenAjax Metadata spec into its final phase where we review/approve the final text within the various chapters. My proposal is to do the following: (1) Remove all of the blue-colored comments that say things like "2008-05-29 Tentatively approved". Let's just assume that everything that exists in the spec today has been tentatively approved. (2) Then we do final review the various sections of the spec and add color-coded notes to indicate status: (a) No color-coding indicates that final review hasn't happened on that particular section. (b) Green-colored Approved indicates that a section has been reviewed and that the text for that section is approved for inclusion in the final spec (c) Purpled-colored comments highlight instructions to the editor for improving the wording in that section of the spec. (d) Red-colored comments reflect issues that require further discussion and resolution. When all sections have a green-colored Approved and all of the purple-colored and red-colored comments are gone, then the spec is done.
Lori: Sounds good
RESOLUTION: Accept proposal for editing the spec going forward