[OpenAjaxIDE] API metadata: multiple returns

Jon Ferraiolo jferrai at us.ibm.com
Fri Aug 29 00:58:46 PDT 2008


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



                                                                           
             Bertrand Le Roy                                               
             <Bertrand.Le.Roy@                                             
             microsoft.com>                                             To 
                                       Bertrand Le Roy                     
             08/28/2008 03:37          <Bertrand.Le.Roy at microsoft.com>,    
             PM                        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

Inactive hide details for Lori Hylan-Cho <lorihc at aptana.com>Lori Hylan-Cho
<lorihc at aptana.com>


                                                                           
                         Lori                                              
                         Hylan-Cho                                         
                         <lorihc at apta                                      
                         na.com>                                           
                         Sent by:                                       To 
                         ide-bounces@                                      
                         openajax.org                "ide at openajax.org"    
                                                     <ide at openajax.org>    
                                                                           
                         08/28/2008                                     cc 
                         12:53 PM                                          
                                                     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/27cc181c/attachment-0001.html 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: graycol.gif
Type: image/gif
Size: 105 bytes
Desc: not available
Url : http://openajax.org/pipermail/ide/attachments/20080829/27cc181c/attachment-0003.gif 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: pic27119.gif
Type: image/gif
Size: 1255 bytes
Desc: not available
Url : http://openajax.org/pipermail/ide/attachments/20080829/27cc181c/attachment-0004.gif 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: ecblank.gif
Type: image/gif
Size: 45 bytes
Desc: not available
Url : http://openajax.org/pipermail/ide/attachments/20080829/27cc181c/attachment-0005.gif 


More information about the IDE mailing list