[OpenAjaxIDE] API metadata: multiple returns

Bertrand Le Roy Bertrand.Le.Roy at microsoft.com
Fri Aug 29 23:16:18 PDT 2008


Yes, but see, one the one hand I agree that the factory problem is hard to solve, but on the other hand it’s about the only good reason to have varying return types.
Allowing multiple static return types only encourages bad practice (but OpenAjax is not especially about enforcing good practice so I wouldn’t oppose them) and fails to solve the only case that really matters.
This type of factory is actually very, very common and worth spending some time investigating.

So let’s see. The way we specify simple types currently, you can pretty much evaluate the type and get a valid reference to the type constructor, right? The type really is an expression that resolves to an actual concrete type/constructor. There is a precedent in JavaScript in terms of name resolution, so if you could specify a parameter name, even if there is potential for naming conflict there, you could apply the same rules of resolution. Here’s something that could work without being too complex:
If you have a factory such as createInstance(type, options), you would document it like so:
 <method name="createInstance" scope="instance">
    <description>A method that creates an instance of a class and sets properties on it.</description>
    <parameters>
       <parameter name="type" required="true" datatype="Function">
          <description>The constructor of the class to create.</description>
       </parameter>
       <parameter name="options " required="false" datatype="Object">
          <description>An associative array of property values to set.</description>
       </parameter>
    </parameters>
    <returns datatype="type">
       <description>The created instance.</description>
    </returns>
 </method>
The Google sample from Lori’s e-mail is a little more difficult because the return type is actually not a trivial expression of the parameters but using a type name instead of a type in factories is so common that we could include that special case. So here’s what the metadata for the Google create method could look like:
<method name="create" scope="instance">
    <description>A method that creates an instance of a class from its type name.</description>
    <parameters>
       <parameter name="type" required="true" datatype="String">
          <description>The constructor of the class to create.</description>
       </parameter>
    </parameters>
    <returns datatype="type">
       <description>The created instance.</description>
    </returns>
 </method>

The type specification for the return type here still is “type”, but the IDE can look at the type for that parameter and infer what it should do from it: if it’s a function, use that as the constructor, and if it’s a string, evaluate that string to get the actual type (when the value is known, which is the case when it’s a string literal).
I realize this increases the complexity of the spec somehow but it is *a lot* more useful than multiple return types (which also comes with added complexity).

From: Jon Ferraiolo [mailto:jferrai at us.ibm.com]
Sent: Friday, August 29, 2008 12:59 AM
To: Bertrand Le Roy
Cc: Bertrand Le Roy; ide at openajax.org; Kevin Lindsey; Lori Hylan-Cho
Subject: RE: [OpenAjaxIDE] API metadata: multiple returns


Hi Bertrand,
I'm not sure we can solve the factory problem very well other than setting datatype to Object and allowing the IDE to display the text found in the <description> tag so that developers can see in words that the Object that is returned requires complex processing.

Regarding what to do with the multiple return types, I was thinking that that's up to the tool, but I would expect most tools would concatenate somehow, perhaps with a divider line between each of the return types, such as a popup that says the following:

---------------------------------------------
|MyFunction(a,b)
|Parameters:
|a - Descriptive text for a
|b - Description text for b
|Returns:
|{type=Object} Descriptive text for the first return type
|--------
|{type=String} Descriptive text for the second return type
---------------------------------------------

Jon

[cid:image001.gif at 01C90A29.3EC9A8B0]Bertrand Le Roy <Bertrand.Le.Roy at microsoft.com>

Bertrand Le Roy <Bertrand.Le.Roy at microsoft.com>

08/28/2008 03:37 PM


To


Bertrand Le Roy <Bertrand.Le.Roy at microsoft.com>, Jon Ferraiolo/Menlo Park/IBM at IBMUS, Lori Hylan-Cho <lorihc at aptana.com>


cc


Kevin Lindsey <klindsey at aptana.com>, "ide at openajax.org" <ide at openajax.org>


Subject


RE: [OpenAjaxIDE] API metadata: multiple returns








Plus, what would you do with multiple return types? Merge all members and present them all?

From: Bertrand Le Roy
Sent: Thursday, August 28, 2008 3:36 PM
To: 'Jon Ferraiolo'; Lori Hylan-Cho
Cc: Kevin Lindsey; ide at openajax.org
Subject: RE: [OpenAjaxIDE] API metadata: multiple returns

Multiple return tags don’t solve the factory problem…

From: ide-bounces at openajax.org [mailto:ide-bounces at openajax.org] On Behalf Of Jon Ferraiolo
Sent: Thursday, August 28, 2008 3:28 PM
To: Lori Hylan-Cho
Cc: Kevin Lindsey; ide at openajax.org
Subject: Re: [OpenAjaxIDE] API metadata: multiple returns

Hi Lori,
I have been waiting for someone to bring up <returns>. Our tentative resolution from six months ago was that we would only allow a single <returns> element but that it could represent multiple return types via the pipe symbol (e.g., <returns datatype="String|Object"/> But I now think that we went the wrong direction and that we should adopt the approach that Aptana ScriptDoc has taken, where there can be multiple <return> (or <returnType> or <return-type>) elements. I came to this conclusion when writing the JSDoc to OpenAjax converter. I'll bet that Aptana noticed the same thing when writing their sdoc to ScriptDocXML converter.

Besides how this makes conversion from JSDoc or sdoc easier, there is also the argument that the different return types warrant different <description> elements (and <remarks>, <title>, <examples>, etc.)

Regarding <seealso>, 1-2 months ago we actually decided to rename the element to <reference>. The descriptive elements and attributes chapter shows the new names:
* http://www.openajax.org/member/wiki/OpenAjax_Metadata_Specification_Descriptive
but I neglected to update the other chapters. I have fixed things now.

Jon

[cid:image001.gif at 01C90A29.3EC9A8B0]Lori Hylan-Cho <lorihc at aptana.com>
Lori Hylan-Cho <lorihc at aptana.com>
Sent by: ide-bounces at openajax.org

08/28/2008 12:53 PM

To


"ide at openajax.org" <ide at openajax.org>

cc


Kevin Lindsey <klindsey at aptana.com>

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');
db.open();

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.

cheers,
Lori


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



_______________________________________________
IDE mailing list
IDE at openajax.org
http://openajax.org/mailman/listinfo/ide
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://openajax.org/pipermail/ide/attachments/20080829/c798b002/attachment-0001.html 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: image001.gif
Type: image/gif
Size: 105 bytes
Desc: image001.gif
Url : http://openajax.org/pipermail/ide/attachments/20080829/c798b002/attachment-0001.gif 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: image003.png
Type: image/png
Size: 168 bytes
Desc: image003.png
Url : http://openajax.org/pipermail/ide/attachments/20080829/c798b002/attachment-0002.png 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: image004.png
Type: image/png
Size: 166 bytes
Desc: image004.png
Url : http://openajax.org/pipermail/ide/attachments/20080829/c798b002/attachment-0003.png 


More information about the IDE mailing list