Some Eclipse Foundation services are deprecated, or will be soon. Please ensure you've read this important communication.

Bug 341172

Summary:	Document what type parameters we support in our jsdoc
Product:	[ECD] Orion	Reporter:	John Arthorne <john.arthorne>
Component:	Client	Assignee:	John Arthorne <john.arthorne>
Status:	RESOLVED FIXED	QA Contact:
Severity:	normal
Priority:	P3	CC:	christophe.cornu+eclipse, eclipse.felipe, mamacdon, Silenio_Quarti
Version:	unspecified
Target Milestone:	0.3 M1
Hardware:	PC
OS:	Windows 7
Whiteboard:

Description John Arthorne

2011-03-28 17:24:08 EDT

We should document what type parameters we support in our jsdoc (mainly used in @param tags). If we are consistent here then we might be able to use this type data for js tooling.

Here is a potential list we can adopt:

http://code.google.com/closure/compiler/docs/js-for-compiler.html#types

Also worth nothing, a request was made for the author of jsdoc to document this, but he declined:

http://code.google.com/p/jsdoc-toolkit/issues/detail?id=282

Comment 1 Christophe Cornu

2011-03-28 20:07:38 EDT

Jazz & C/LM should consider the benefits of adopting the same jsdoc conventions to describe javascript api's.

Comment 2 Felipe Heidrich

2011-03-29 09:26:17 EDT

(In reply to comment #0)
> We should document what type parameters we support in our jsdoc (mainly used in
> @param tags). If we are consistent here then we might be able to use this type
> data for js tooling.

What do you mean by type parameters ?
In the mailing list you mention something about only using the return values of "typeof".
In the Editor we used user defined types and they work great. For example:
http://orion.eclipse.org/jsdoc/symbols/eclipse.Editor.html#addRuler

Note that eclipse.Ruler does not exist as a symbol in javascript, the type is entirely document in the jsdoc. (what exists, for example, is eclipse.LineNumberRuler which implements the eclipse.Ruler interface).

Other way to document an user defined type is what we did for the constructor:
http://orion.eclipse.org/jsdoc/symbols/eclipse.Editor.html#constructor
There, instead of declaring a eclipse.EditorOptions type, we described each field of the options object inline.


> 
> Here is a potential list we can adopt:
> 
> http://code.google.com/closure/compiler/docs/js-for-compiler.html#types
> 

that syntax is not the same as jsdoc:
http://code.google.com/p/jsdoc-toolkit/wiki/TagParam

Comment 3 Felipe Heidrich

2011-03-29 09:35:03 EDT

(In reply to comment #2)
> 
> that syntax is not the same as jsdoc:
> http://code.google.com/p/jsdoc-toolkit/wiki/TagParam

In the Editor we used all the formats described in the link above.

One case we didn't use a formal notation was for Function type:
* @param {Function} func the function that will be executed when the event happens. 
*   The function should take an event as the first parameter and optional data as the second parameter.

(http://orion.eclipse.org/jsdoc/symbols/eclipse.Editor.html#addEventListener)
As you see the parameters (and return type) for the func are only described in the description. I am not 100% sure, but this can be a limitation of jsdoc.

Comment 4 John Arthorne

2011-07-20 11:49:02 EDT

I didn't fully understand jsdoc when I entered this. The answer really is that "type names" are a construct of jsdoc - whatever you put next to @name is the name of the type, and if you put the same name in an @param it will match up. You can also use the primitive types: Object, String, Number, Boolean, Function. I have added some basic doc here:

http://wiki.eclipse.org/Orion/Coding_conventions#JavaScript