[OpenAjaxIDE] more optional/required attributes

Jon Ferraiolo jferrai at us.ibm.com
Wed Sep 10 18:10:09 PDT 2008


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




                                                                           
             Bertrand Le Roy                                               
             <Bertrand.Le.Roy@                                             
             microsoft.com>                                             To 
                                       Jon Ferraiolo/Menlo Park/IBM at IBMUS  
             09/10/2008 05:34                                           cc 
             PM                        "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 microso                                      
                         ft.com>                                        To 
                                                                           
                                               Jon Ferraiolo/Menlo         
                         09/10/2008            Park/IBM at IBMUS              
                         03:29 PM                                          
                                                                        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>                         
                                                               Lori        
                                                               Hylan-Cho   
                                           09/10/2008          <lorihc at apt 
                                           12:44 PM            ana.com>,   
                                                               "ide at openaj 
                                                               ax.org"     
                                                               <ide at openaj 
                                                               ax.org>,    
                                                               Jon         
                                                               Ferraiolo/M 
                                                               enlo        
                                                               Park/IBM at IB 
                                                               MUS         
                                                                        cc 
                                                                           
                                                                   Subject 
                                                                           
                                                               RE:         
                                                               [OpenAjaxID 
                                                               E] more     
                                                               optional/re 
                                                               quired      
                                                               attributes  
                                                                           
                                                                           
                                                                           
                                                                           
                                                                           
                                                                           
                                                                           
                                                                           
                                                                           
                                                                           
                                                                           
                                                                           





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/20080910/7b998f84/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/20080910/7b998f84/attachment-0003.gif 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: pic08931.gif
Type: image/gif
Size: 1255 bytes
Desc: not available
Url : http://openajax.org/pipermail/ide/attachments/20080910/7b998f84/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/20080910/7b998f84/attachment-0005.gif 


More information about the IDE mailing list