[OpenAjaxIDE] more optional/required attributes

Jon Ferraiolo jferrai at us.ibm.com
Thu Sep 11 09:12:22 PDT 2008


Having JSDoc-to-OAM conversion generate datatype='Object' works for me.
That also means that we can make 'datatype' be a required attribute on
<return*>, which I believe is one of the recommendations that Lori made
several emails ago.

If we go this route, then I would recommend an informative note in the spec
that highlights the difference between JSDoc (where datatype is optional)
and our spec (where datatype is required) and suggest that conversion tools
generate datatype='Object'.

I have put red-colored comments in the spec raising these topics as things
that need to be decided and attempting to capture the current state of
discussion, but I will wait until Tuesday's phone call before changing to
the spec and the schema.

Jon




I think if you’re going to go out of your way and specify a @returns in
JSDoc, it’s quite likely that the method will actually return something
(otherwise, chances are you’d just have omitted it). So I’d say we should
translate that into retuns datatype=”Object” as this is a pretty good guess
in most cases and there’s little harm done if we’re wrong…

From: Jon Ferraiolo [mailto:jferrai at us.ibm.com]
Sent: Wednesday, September 10, 2008 6:10 PM
To: Bertrand Le Roy
Cc: ide at openajax.org; Lori Hylan-Cho
Subject: RE: [OpenAjaxIDE] more optional/required attributes



Yes, that's right. What I have been thinking all along is that for
situations like this, we could help improve JSDoc by figuring out what the
"right" thing in situations where their spec is incomplete.

We could try to convince the industry that @return must have a 'datatype',
but first off the JSDoc guys might not agree, and if even if they did, it
is guaranteed that not all people will read the spec. In my experience, it
is usually better for specs to define how user agents should act when
values are not specified than attempt to force users into creating content
that contains all of the required elements.

That's why I am asking for opinions about how to convert an unspecified
datatype on @returns (e.g., @returns Here is the description) into OpenAjax
Metadata. It seems the easy answer is to generate a <return*> element
without a 'datatype', but according to our current rules, the default value
for 'datatype' is String, which is not a good default for <return*>. We
could decide that <return*> has a different datatype default than
everything else, but what would that be? Any (i.e., *)? Void? Object? I
think we could also have the notion that <return*> does not have a datatype
default, and expect that IDEs would do something reasonable in this case,
such as saying something like "return type = unknown". That's where I am
leaning now.

Jon


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



                                                                           
                         Bertrand Le                                       
                         Roy                                               
                         <Bertrand.Le                                      
                         .Roy at microso                                      
                         ft.com>                                        To 
                                                                           
                                               Jon Ferraiolo/Menlo         
                         09/10/2008            Park/IBM at IBMUS              
                         05:34 PM                                          
                                                                        cc 
                                                                           
                                               "ide at openajax.org"          
                                               <ide at openajax.org>, Lori    
                                               Hylan-Cho                   
                                               <lorihc at aptana.com>         
                                                                           
                                                                   Subject 
                                                                           
                                               RE: [OpenAjaxIDE] more      
                                               optional/required           
                                               attributes                  
                                                                           
                                                                           
                                                                           
                                                                           
                                                                           
                                                                           
                                                                           
                                                                           
                                                                           
                                                                           





Right, but they’re not saying what it means not to specify it, which is
quite weak…

From:, Jon Ferraiolo [’mailto:jferrai at us.ibm.com.]
Sent:: Wednesday, September 10, 2008 5:33 PM
To: Bertrand Le Roy
Cc: ide at openajax.org; Lori Hylan-Cho
Subject: RE: [OpenAjaxIDE] more optional/required attributes


JSDoc does indeed have a spec. Actually, multiple specs that are slightly
different. Here is one that I found that says the datatype on @return is
optional.

http://jsdoctoolkit.org/wiki/?page=returns


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


                                                                           
       Bertrand Le Roy                                                     
       <Bertrand.Le.Roy at microsoft.com>                                     
                                                                           
                                                                        To 
       09/10/2008 03:29 PM                                                 
                                                  Jon Ferraiolo/Menlo      
                                                  Park/IBM at IBMUS           
                                                                        cc 
                                                                           
                                                  "ide at openajax.org"       
                                                  <ide at openajax.org>, Lori 
                                                  Hylan-Cho                
                                                  <lorihc at aptana.com>      
                                                                   Subject 
                                                                           
                                                  RE: [OpenAjaxIDE] more   
                                                  optional/required        
                                                  attributes               
                                                                           
                                                                           
                                                                           
                                                                           
                                                                           
                                                                           
                                                                           
                                                                           
                                                                           
                                                                           
                                                                           
                                                                           





What does it mean in JSDoc? Is it specified?

From: Jon Ferraiolo [mailto:jferrai at us.ibm.com.]
Sent:: Wednesday, September 10, 2008 3:23 PM
To: Bertrand Le Roy
Cc: ide at openajax.org; Lori Hylan-Cho
Subject: RE: [OpenAjaxIDE] more optional/required attributes


OK, but I have a follow-on question to clarify what you are suggesting. Do
you recommend that a JSDoc-to-OpenAjax converter should do if it encounters
the following (where there is an @return but the datatype is not
specified):

/**
* This is a cool method
* @return blah blah blah (descriptive text but datatype is not specified).
*/

Should the converter produce:

<return*>
<description>blah blah blah (descriptive text but datatype is not
specified).</description>
</return*>

or

<return* datatype='void'>
<description>blah blah blah (descriptive text but datatype is not
specified).</description>
</return*>

or

<return* datatype='Object'>
<description>blah blah blah (descriptive text but datatype is not
specified).</description>
</return*>

Jon


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



The case that you describe is emitting a warning in Firefox strict (and
rightly so). I think this goes a little too far. If the spec happened to
support it as a side effect I’d say yeah, sure, fine, let people do
whatever. But here we would have to actually go out of our way and add new
semantics to cover bad practice (for which there isn’t a good scenario and
for which there is a perfectly good workaround which is to return null in
the case where you return nothing, which by the way is covered by
dataType=”Object”). I’d vote against that.

So to get back to the void thing, the datatype attribute can be mandatory
if we have that, which was Lori’s initial question.

From: Jon Ferraiolo [mailto:jferrai at us.ibm.com.]
Sent:: Wednesday, September 10, 2008 1:40 PM
To: Bertrand Le Roy
Cc: ide at openajax.org; Lori Hylan-Cho
Subject: RE: [OpenAjaxIDE] more optional/required attributes


Bertrand's correct that we already discussed 'undefined' vs 'void' for
<returns> and concluded that it was better to use 'void'. There is a note
about this decision in the Datatypes chapter.

The scenario that we need to worry about is when there is some JSDoc (or
similar inline documentation) that says something like:

/**
* This is a cool method
* @return Sometimes returns nothing, sometimes a number, sometimes an
object, sometimes an array.
*/
function coolMethod() {
...
return;
...
return num;
...
return obj;
...
return arr;
...
}

The key thing to point out in this example is that there is a return
description but no return type. Don't we need to handle that situation
since it is legal in JSDoc? That's why I proposed '*', which allows for any
possible return value, including void.

Regarding <exception>, I'll have to look closer at my JavaScript
references, but maybe '*' maybe sense there also (instead of Error).

Jon,

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


                                                                           
                                                         Bertrand Le       
                                                         Roy               
                                                         <Bertrand.Le      
                                                         .Roy at microso   To 
                                                         ft.com>           
                                                                         L 
                                                                         o 
                                                         09/10/2008      r 
                                                         12:44 PM        i 
                                                                         H 
                                                                         y 
                                                                         l 
                                                                         a 
                                                                         n 
                                                                         - 
                                                                         C 
                                                                         h 
                                                                         o 
                                                                         < 
                                                                         l 
                                                                         o 
                                                                         r 
                                                                         i 
                                                                         h 
                                                                         c 
                                                                         @ 
                                                                         a 
                                                                         p 
                                                                         t 
                                                                         a 
                                                                         n 
                                                                         a 
                                                                         . 
                                                                         c 
                                                                         o 
                                                                         m 
                                                                         > 
                                                                         , 
                                                                         " 
                                                                         i 
                                                                         d 
                                                                         e 
                                                                         @ 
                                                                         o 
                                                                         p 
                                                                         e 
                                                                         n 
                                                                         a 
                                                                         j 
                                                                         a 
                                                                         x 
                                                                         . 
                                                                         o 
                                                                         r 
                                                                         g 
                                                                         " 
                                                                         < 
                                                                         i 
                                                                         d 
                                                                         e 
                                                                         @ 
                                                                         o 
                                                                         p 
                                                                         e 
                                                                         n 
                                                                         a 
                                                                         j 
                                                                         a 
                                                                         x 
                                                                         . 
                                                                         o 
                                                                         r 
                                                                         g 
                                                                         > 
                                                                         , 
                                                                         J 
                                                                         o 
                                                                         n 
                                                                         F 
                                                                         e 
                                                                         r 
                                                                         r 
                                                                         a 
                                                                         i 
                                                                         o 
                                                                         l 
                                                                         o 
                                                                         / 
                                                                         M 
                                                                         e 
                                                                         n 
                                                                         l 
                                                                         o 
                                                                         P 
                                                                         a 
                                                                         r 
                                                                         k 
                                                                         / 
                                                                         I 
                                                                         B 
                                                                         M 
                                                                         @ 
                                                                         I 
                                                                         B 
                                                                         M 
                                                                         U 
                                                                         S 
                                                                        cc 
                                                                           
                                                                      Subj 
                                                                       ect 
                                                                           
                                                                         R 
                                                                         E 
                                                                         : 
                                                                         [ 
                                                                         O 
                                                                         p 
                                                                         e 
                                                                         n 
                                                                         A 
                                                                         j 
                                                                         a 
                                                                         x 
                                                                         I 
                                                                         D 
                                                                         E 
                                                                         ] 
                                                                         m 
                                                                         o 
                                                                         r 
                                                                         e 
                                                                         o 
                                                                         p 
                                                                         t 
                                                                         i 
                                                                         o 
                                                                         n 
                                                                         a 
                                                                         l 
                                                                         / 
                                                                         r 
                                                                         e 
                                                                         q 
                                                                         u 
                                                                         i 
                                                                         r 
                                                                         e 
                                                                         d 
                                                                         a 
                                                                         t 
                                                                         t 
                                                                         r 
                                                                         i 
                                                                         b 
                                                                         u 
                                                                         t 
                                                                         e 
                                                                         s 
                                                                           
                                                                           
                                                                           
                                                                           
                                                                           
                                                                           
                                                                           
                                                                           
                                                                           
                                                                           
                                                                           
                                                                           





Actually no, it’s not totally accurate. Returning undefined and not
returning anything is subtly different (and Firefox in strict mode may flag
the difference with a warning).
Sure, I don’t think anyone will ever use undefined to mean that they will
explicitly return something that is undefined but I thought I’d make the
point anyway. I think we had that exact same discussion a while ago when we
discussed “void”.

From: ide-bounces at openajax.org [mailto:ide-bounces at openajax.org.] On Behalf
Of Lori Hylan-Cho
Sent: Wednesday, September 10, 2008 11:12 AM.
To: ide at openajax.org; Jon Ferraiolo
Subject: Re: [OpenAjaxIDE] more optional/required attributes

If we're not going to require datatype on <returns>, I'd vote for undefined
as the default value. It's accurate, and it's in line with what functions
that just return; do.

As for <exception>, I'm not sure that a default of 'Error' is any more
informative than no datatype at all. Is it likely that library authors will
want to put empty, attributeless <exception /> tags in their metadata?

From: Jon Ferraiolo [mailto:jferrai at us.ibm.com.]
Sent:: Wednesday, September 10, 2008 12:04 PM
To: Lori Hylan-Cho
Cc: ide at openajax.org
Subject: Re: [OpenAjaxIDE] more optional/required attributes>,


Hi Lori,
I looked at JSDoc and it says that the type value is optional on @returns.
(http://jsdoctoolkit.org/wiki/?page=returns) Therefore, it seems to me that
we should try to make 'datatype' on our <returns> element optional, also.
But that raises the question about what is the default 'datatype' for
<returns> in case 'datatype' is not specified. I would guess "*" is the
best default value for 'datatype' on <returns>.

Regarding <exception>, once again JSDoc says that the type is optional on
@throws, so once again I think we should make datatype optional on
<exception>. I would guess that 'Error' would be the best default value for
'datatype' on <exception>.

Jon


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



Hi again

Our developer came across two other attributes that are listed as optional
in the API metadata spec but that we need to be required. Actually, they're
the same attribute -- datatype -- on two different tags. One is <returns>,
which we discussed today. It seems like datatype is the whole reason for
the <returns> tag's existence. (As we talked about today, paramType and
paramValue, the two new attributes for <returns>, can be optional.)

The other tag is <exception>, where we think datatype is also essential.

Let me know if anyone disagrees.

Lori

-----------------------------------------------------------------------
Lori Hylan-Cho Ajax Wrangler Aptana, Inc.
lorihc at aptana.com 650.207.1905 avocadoh (Y!/AIM/GTalk)
_______________________________________________
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/20080911/e3a9e16e/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/20080911/e3a9e16e/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/20080911/e3a9e16e/attachment-0003.gif 


More information about the IDE mailing list