Community
Participate
Working Groups
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
Jazz & C/LM should consider the benefits of adopting the same jsdoc conventions to describe javascript api's.
(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
(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.
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
