search

AaronNGray / jsdoc-toolkit

Automatically exported from code.google.com/p/jsdoc-toolkit
0 stars 0 forks source link

Provide information on valid parameter types #282

Closed GoogleCodeExporter closed 9 years ago

GoogleCodeExporter commented 9 years ago 
The documentation at 

http://code.google.com/p/jsdoc-toolkit/wiki/TagParam

explains how type annotations can be added to function parameters, but it 
does not explain what constitutes a valid type.  I assume anything returned 
by "typeof" is a valid type (provided the first letter is uppercased), but 
the page itself doesn't state this.  Does @param also accept object types?  
(i.e. if "foo instanceof Foo === true", is "Foo" also a valid type?)

See also

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

It would be useful if the same type annotations were supported.  Note that 
the Google Closure compiler--even though it says it type annotations are 
derived from JSDoc--does not accept "{function}" as a valid type.  (I've 
logged a bug for this.)

Original issue reported on code.google.com by ithinkihaveacat on 11 Feb 2010 at 11:01

GoogleCodeExporter commented 9 years ago 
if "foo instanceof Foo === true", is "Foo" also a valid type? Yes. But remember 
we are dealing with 
documentation here, so if you've *documented* something named "Foo" then that 
is what makes it valid to refer 
to Foo as a type. Doing this will mean that in the output those types will be 
turned into HTML links to the 
documentation pages for those symbols. On the other hand you can put any word 
you want there and it 
shouldn't break anything.

I'm willing to accept contributions of code to do google-style annotations but 
it's not something I have the 
inclination or time to write myself.

Original comment by micmath on 14 Mar 2010 at 8:27

GoogleCodeExporter commented 9 years ago 
Leaving aside the situation with object types, which is more complicated, would 
it be 
possible to at least the valid primitive types in the TagParam documentation?  
I think 
this would be particularly useful to people unfamiliar with JavaScript, and who 
are 
wondering if, for example "int" or "integer" or "double" or "number" are valid 
types.  (If 
the types accepted by JSDoc have no correspondence with valid JS types (i.e. if 
JSDoc will 
accept any string), then this would also be useful to know.)

Original comment by ithinkihaveacat on 14 Mar 2010 at 8:40