[OpenAjaxIDE] more optional/required attributes

Jon Ferraiolo jferrai at us.ibm.com
Wed Sep 10 17:32:48 PDT 2008


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




                                                                           
             Bertrand Le Roy                                               
             <Bertrand.Le.Roy@                                             
             microsoft.com>                                             To 
                                       Jon Ferraiolo/Menlo Park/IBM at IBMUS  
             09/10/2008 03:29                                           cc 
             PM                        "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 microsoft.c                                    
           om>                                                             
                                                                        To 
                                                                           
           09/10/2008 12:44 PM                Lori Hylan-Cho               
                                              <lorihc at aptana.com>,         
                                              "ide at openajax.org"           
                                              <ide at openajax.org>, Jon      
                                              Ferraiolo/Menlo              
                                              Park/IBM at IBMUS               
                                                                        cc 
                                                                           
                                                                   Subject 
                                                                           
                                              RE: [OpenAjaxIDE] more       
                                              optional/required 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/fac062cc/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/fac062cc/attachment-0003.gif 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: pic13770.gif
Type: image/gif
Size: 1255 bytes
Desc: not available
Url : http://openajax.org/pipermail/ide/attachments/20080910/fac062cc/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/fac062cc/attachment-0005.gif 


More information about the IDE mailing list