IDE Minutes 2009 01-20

From MemberWiki

Jump to: navigation, search

URL: http://www.openajax.org/member/wiki/IDE_Minutes_2009_01-20

Contents

Attendees

  • Jon Ferraiolo, IBM
  • Kin Blas, Adobe
  • Lori Hylan-Cho, Aptana
  • Nitin Dahyabhai, IBM
  • Bertrand Le Roy, Microsoft

Minutes

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

RESOLUTION: Approved

Is this paragraph for the <api> element OK?

The first paragraph in the description of the <api> element reads as
follows:
-----------------------
The <api> element is the root element of an OpenAjax Metadata file that
defines JavaScript APIs. An Ajax library may define all of its APIs within
a single OpenAjax Metadata file or split the API definitions across
multiple OpenAjax Metadata files. If multiple OpenAjax Metadata files are
used, then those files should be located within the same directory tree
(not necessarily the same directory) so that IDEs can discover all of the
metadata files in order to resolve dependencies. WG should review this
paragraph.
-----------------------

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.

Jon: Yes

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>

The description of the 'datatype' attribute for the <ancestor> element now
reads as follows:
--------------------
The datatype attribute specifies either the ancestor class name or ancestor
interface name. The detailed description of the datatype attribute can be
found in the Datatypes chapter. However, for the <ancestor> element, the
value can only be the name of a class or interface and cannot be one of the
core JavaScript datatypes (such as String or Object). Needs review: is this
description correct?
--------------------

Lori: Why not any JavaScript type?

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

Personal tools