IDE Minutes 2008-04-08
- Stew Nickolas, IBM
- Lori Hylan-Cho, Adobe
- Jon Ferraiolo, IBM
- Ted Thibodeau, OpenLink
- Ingo Muschenetz, Aptana
- Kevin Hakman, Aptana
- Bertrand Le Roy, Microsoft
- Phil Berkland, IBM
- Rich Thompson, IBM
Kevin: Last week made good progress. Got about 10 or less items to discuss. Some open items--Betrand to draft a proposal on those.
Bertand: I unfortunately didn't have time
Kevin: Moving onto <remarks>
Ingo: It's basically an extended description for more information
Kevin: Laurie and Bertrand, is that something you find necessary?
Bertrand: We have that element
Lori: Where is that useful? I can think of a use case where we could use it, but we're not using it right now
Bertrand: It's one of those things that allows you to structure your description more than plain text
Jon: What are the requirements on the IDE?
Kevin: It's optional for the tool to display and in whatever format the tool decides
Lori: My only quibble was with the name remarks. It seems very informal
Jon: What name would you choose?
Ingo: We chose it because it was similar to other items, such as in JavaDoc
Bertrand: Is it a sibling or child of description?
Ingo: In our case, it's a sibling
Jon: I'd suggest sibling pending Betrand's research on what Microsoft does. What elements does it attach to?
Ingo: We use it on class, property and method
Kevin: return-description: So that becomes a child of the <returns> element. Any objctions to that?
Kevin: next item is @scope
Ingo: Is that a hinting mechanism for the documentation generation?
Jon: it seems to be useful in the JSDoc to XML generation.
Kevin: It seems redundant to our current scope attribute. Any objections to removing it? Okay, removed.
Kevin: @sdoc. This seems like an Aptana thing.
Ingo: It's to reference an external documentation file
Kevin: @see: Waiting on a proposal from Bertrand
Bertrand: I've asked, but not had a response yet
Kevin: @since. Seems like an Aptana thing
Jon: Looking before the meeting, it's seems like we may made a mistake in omitting availablility. It could just be text
Kevin: I agree it might be useful to just capture the text.
Kevin: Any objection to reinstating availability and since?
Rich: Perhaps 'available' is a better term?
Jon: To confirm, 'deprecated' and 'available' elements with version attributes and text descriptions? So the specifications node is an Aptana specific thing?
Ingo: Yes, I think we can do that using extensions
Kevin: Next item in the matrix is static? I think we've handed that already
Ingo: It's the same, useful for JSDoc to HTML generation
Kevin: Moving on to value and values. It's effectively enumerations
Bertrand: In Microsoft, the enumerations are just fields. This "values" construct works but requires a bunch of repetition. We're fine with it, but one concern is how would other IDEs be able to look at the enumeration type and show the enumerations?
Kevin: Doesn't a concept of a class capture that?
Bertrand: Not exactly.
Ingo: We don't have that much repetition
Bertrand: We make great use of enumeration types. There are also enumerations and flags
Kevin: Is this an area where you'd like to put together a proposal? Something where there are both of those cases would be useful to show. Thanks bertand
Jon: Can I make a draft consensus about <values><value>?
Ingo: We need to make an example of using flag or flags as Betrand had suggested
Kevin: Jon, for now can we make some semantics about what to call.
Kevin: @version. Looks like an Aptana thing
Ingo: it's the version of the whole library, i.e. jQuery 1.2.3
Kevin: Any objection to including that? This would be an attribute on the API element. Okay, approved.
Kevin: Items left: "type" attribute on <alias>
Ingo: We used that in a very specialized circumstance which isn't required here. It can be removed.
Kevin: How about the <browsers> element?
Ingo: I think we changed it to the useragent element.
Bertrand: What Aptana has done here is well-thought out, and will work well here. How does the versions attribute work?
...some discussion about possibilities about the version attribute... end result is "-3.0" is less than, "3.0" is exact, "2.0-3.0" is range, "3.0+" is equal to and greater than
Kevin: We're at the end of the hour. We'll pick up discussion next week.