[OpenAjaxIDE] API metadata: multiple returns

Jon Ferraiolo jferrai at us.ibm.com
Thu Sep 4 10:53:57 PDT 2008


Here are some suggested tweaks to what Lori and Bertrand are proposing.

Instead of introducing 'paramId', how about the introducing a 'condition'
attribute to the <returns> element. That way the mechanism can work if the
value is an enumeration of strings (as in Lori's example) or just a string.
I realize that introducing a subgrammar has disadvantages, but I think my
proposed syntax will be reasonably self-documenting to people looking at
the metadata file. See below.

<method name="create" scope="instance">
    <description>Creates a Gears object of the given class.</description>
    <parameters>
       <parameter name="className" required="true" datatype="String">
          <description>The class to create.</description>
       <options>
       <option value="beta.database" />
       <option value="beta.localserver" />
       …
       </options>
       </parameter>
       <parameter name="options " required="false" datatype="Object">
          <description>An associative array of property values to
set.</description>
       </parameter>
    </parameters>
    <returns condition="parameter(className)=beta.database"
datatype="Database">
       <description>An instance of the Database class.</description>
    </returns>
    <returns condition="parameter(className)=beta.localserver"
datatype="LocalServer">
       <description>An instance of the LocalServer class.</description>
    </returns>
    …
 </method>

For Bertrand's case where he wants to use the prameter name as the return
type, we could add allow the 'datatype' attribute to support the syntax
"parameter(foo)" when used on the <returns> element. For example:>

<method name="factory">
    <parameters>
       <parameter name="className" required="true" datatype="String">
          <description>The class to create.</description>
       </parameter>
    </parameters>
    <returns datatype="parameter(className)">
       <description>An instance of the class specified by the className
parameter.</description>
    </returns>
    …
 </method>

As Bertrand has proposed, the processing model would be that the parameter
could be either a String (i.e., the class name) or a Function (i.e., the
constructor). (Although I'm a little fuzzy exactly how you can determine
the classname from the Function object. How can you tell it isn't an
anonymous function? Excuse my ignorance, and I'm writing this on a plane
and I don't have my JavaScript book with me.)

Another thing. If we allow multiple <returns> elements, for consistency
reasons with the rest of the language, we should have a plural and singular
versions of the elements. Aptana ScriptDocXML has <return-types> and
<return-type>, which is OK, but for compound words we have been using
camelcase, so I would prefer <returnTypes> and <returnType> or maybe the
shorter version of <returns> and <return>.

Jon




Yes, that makes it clearer (although one wonders why there aren’t just a
createDataBase and a createLocalServer function…).
If we have that *and* the generic factory implementation where one can use
a parameter name as the return type, I’m fine with it.

From: Lori Hylan-Cho [mailto:lorihc at aptana.com]
Sent: Tuesday, September 02, 2008 3:37 PM
To: Bertrand Le Roy; Jon Ferraiolo
Cc: ide at openajax.org; Kevin Lindsey
Subject: RE: [OpenAjaxIDE] API metadata: multiple returns

OK, here's one other stab at it. The idea is that there'd be a way to match
up the various fixed argument options with their corresponding return
types.

<method name="create" scope="instance">
    <description>Creates a Gears object of the given class.</description>
    <parameters>
       <parameter name="className" required="true" datatype="String">
          <description>The class to create.</description>
       <options>
       <option value="beta.database" paramId="db" />
       <option value="beta.localserver" paramId="local" />
       …
       </options>
       </parameter>
       <parameter name="options " required="false" datatype="Object">
          <description>An associative array of property values to
set.</description>
       </parameter>
    </parameters>
    <returns paramId="db" datatype="Database">
       <description>An instance of the Database class.</description>
    </returns>
    <returns paramId="local" datatype="LocalServer">
       <description>An instance of the LocalServer class.</description>
    </returns>
    …
 </method>
I think the other, more general case I was thinking of is really best
described by multiple function signatures. That is, a version of foo() that
takes a string and returns an Object would be listed as


<method name="foo" scope="instance">
    <description>Get the Object corresponding to theString.</description>
    <parameters>
       <parameter name="theString" required="true" datatype="String">
          <description>The string for which to find an
Object.</description>
       </parameter>
    </parameters>
    <returns datatype="Object">
       <description>The Object corresponding to theString.</description>
    </returns>
 </method>

while the verion of foo() that takes an array of strings and returns an
array of objects would be listed as

 <method name="foo" scope="instance">
    <description>Get the Object corresponding to each string in
stringArray.</description>
    <parameters>
       <parameter name="stringArray" required="true" datatype="[String]">
          <description>The array of strings for which to find
Objects.</description>
       </parameter>
    </parameters>
    <returns datatype="[Object]">
       <description>The Object corresponding to theString.</description>
    </returns>
 </method>

Right now most libraries that provide ScriptDoc files to us seem to combine
all their variations into a single method description rather than breaking
them out by signature, the variations end up as text hints, and only the
first return type has any meaning for code hints. Not very helpful, IMHO.

So, does that make sense, or am I totally confusing things? FWIW, I think
Bertrand's example or a variation of it could still work for the factory
case where the argument == the return type.

Lori



From: Bertrand Le Roy [mailto:Bertrand.Le.Roy at microsoft.com]
Sent: Saturday, August 30, 2008 2:16 AM
To: Jon Ferraiolo
Cc: ide at openajax.org; Kevin Lindsey; Lori Hylan-Cho
Subject: RE: [OpenAjaxIDE] API metadata: multiple returns

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

Inactive hide details for Bertrand Le Roy <Bertrand.Le.Roy at microsoft.com>
Bertrand Le Roy <Bertrand.Le.Roy at microsoft.com>


                                                                           
                         Bert                                              
                         rand                                              
                         Le                                                
                         Roy                                               
                         <Ber                                           To 
                         tran                                              
                         d.Le        Bertrand Le Roy                       
                         .Roy        <Bertrand.Le.Roy at microsoft.com>, Jon  
                         @mic        Ferraiolo/Menlo Park/IBM at IBMUS, Lori  
                         roso        Hylan-Cho <lorihc at aptana.com>         
                         ft.c                                              
                         om>                                            cc 
                                                                           
                                     Kevin Lindsey <klindsey at aptana.com>,  
                         08/2        "ide at openajax.org" <ide at openajax.org> 
                         8/20                                              
                         08                                        Subject 
                         03:3                                              
                         7 PM        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 aptana.com>                                        
 Sent by: ide-bounces at openajax.org                                         
                                                                           
                                                                        To 
 08/28/2008 12:53 PM                                                       
                                                         "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/20080904/1d1a2650/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/20080904/1d1a2650/attachment-0002.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/20080904/1d1a2650/attachment-0003.gif 


More information about the IDE mailing list