[OpenAjaxIDE] more optional/required attributes

Bertrand Le Roy Bertrand.Le.Roy at microsoft.com
Wed Sep 10 21:30:58 PDT 2008


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


[cid:image001.gif at 01C9138C.83B75870]Bertrand Le Roy <Bertrand.Le.Roy at microsoft.com>

Bertrand Le Roy <Bertrand.Le.Roy at microsoft.com>

09/10/2008 05:34 PM


To


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








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


[cid:image001.gif at 01C9138C.83B75870]Bertrand Le Roy <Bertrand.Le.Roy at microsoft.com>
Bertrand Le Roy <Bertrand.Le.Roy at microsoft.com>

09/10/2008 03:29 PM

To


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


[cid:image001.gif at 01C9138C.83B75870]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

[cid:image001.gif at 01C9138C.83B75870]Bertrand Le Roy <Bertrand.Le.Roy at microsoft.com>
Bertrand Le Roy <Bertrand.Le.Roy at microsoft.com>

09/10/2008 12:44 PM

To


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


[cid:image001.gif at 01C9138C.83B75870]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/afc83b0a/attachment-0001.html 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: image001.gif
Type: image/gif
Size: 105 bytes
Desc: image001.gif
Url : http://openajax.org/pipermail/ide/attachments/20080910/afc83b0a/attachment-0001.gif 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: image002.png
Type: image/png
Size: 168 bytes
Desc: image002.png
Url : http://openajax.org/pipermail/ide/attachments/20080910/afc83b0a/attachment-0002.png 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: image003.png
Type: image/png
Size: 166 bytes
Desc: image003.png
Url : http://openajax.org/pipermail/ide/attachments/20080910/afc83b0a/attachment-0003.png 


More information about the IDE mailing list