[OpenAjaxIDE] API metadata: multiple returns

Bertrand Le Roy Bertrand.Le.Roy at microsoft.com
Thu Aug 28 13:43:21 PDT 2008


Factory methods are quite tricky because the return type is pretty much runtime information. Surfacing that on the metadata pretty much amounts to reproducing parts of the function implementation as metadata.
The simplest option is of course to just use Object as the return type. Not great.
We could have some form of expression that could depend on parameters (something like type="{{typeName}}" where typeName is the name of the parameter) but it could get complex quite fast.
Also, if you had such an expression for a type, how do you express the Google example below and differentiate it from the following:
$create(Sys.UI.DataView, ...)
where the return type is not expressed as a string but as the type object itself?
Generally, there are few good reasons to have varying return types, but here's another one: JSON deserialization into a specific type (not something I'd recommend myself but it's a common enough practice). In that case, it's even trickier because the return type might be buried more or less deep into one of the parameters.


-----Original Message-----
From: ide-bounces at openajax.org [mailto:ide-bounces at openajax.org] On Behalf Of Lori Hylan-Cho
Sent: Thursday, August 28, 2008 12:53 PM
To: ide at openajax.org
Cc: Kevin Lindsey
Subject: [OpenAjaxIDE] API metadata: multiple returns

hi all

I know we've been focusing on the widget[/gadget/mashup] metadata lately, but at Aptana we're starting to work on implementing the API metadata, and I have some questions about that. (It seemed like we finished with the API metadata months ago, but the spec's still pretty short on details and long on TO BE WRITTENs.)

The first thing I need guidance on is multiple return types. Currently we have a <returns> tag that doesn't have a plural container (probably because the verb "returns" already ends in s). Are we going to allow multiple <returns> tags as children of <constructor>, <method>, etc.? There are a couple libraries I can think of off the top of my head that need this -- and one at least will also need a way to indicate which return type applies to which case. For example, in Google gears, the Factory.create() method creates various objects based on the string passed to it.

  // Instantiate Gears objects
  var db = google.gears.factory.create('beta.database');

In this case, db is a Database object, but if I had passed "beta.desktop", I'd have gotten a Desktop object, "beta.localserver" would have given me a LocalServer object, etc. It'd be great if the metadata could express a relationship between the argument and the return value, but I don't have a good idea of how to do that.

One other issue I have in mapping our current method of describing APIs to the OAA format is the <seealso> tag. I *think* this is analogous to our <reference> tag, but as <seealso> (http://www.openajax.org/member/wiki/OpenAjax_Metadata_Specification_API_Metadata#.3Cseealso.3E) seems to have been omitted from the Descriptive elements and attributes chapter, I'm not sure.


Lori Hylan-Cho
Ajax Wrangler
Aptana, Inc.
lorihc at aptana.com

IDE mailing list
IDE at openajax.org

More information about the IDE mailing list