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