| Documenting the parameters and a function? JSDoc again... [message #1013408] |
Sat, 23 February 2013 10:40  |
 Jari Pennanen
Messages: 1
Registered: July 2009 |
Junior Member |
|
|
Example:
/**
* Test
*
* @param a The super number
* @param b The other number
* @param c Something fancy
*/
function test(a, b, c) { // < String test(Number a, Number b, String c)
return (a + b) + "" + c
}
VJET does not seem to support documenting the parameters or the function, which I think should be supported. Also the syntax above is not very clean.
My proposal is to invent a new jsdoc attribute which contains the signature inside the traditional jsdoc, e.g. using invented "@types".
* ...
* @param b The other number
* @param c Something fancy
* @types String fn(Number a, Number b, String c)
* ...
If function / method has a really complicated signature requiring multiple definitions it could be simply written by duplicating the line:
* ...
* @types String fn(Number a, Number b, String c)
* @types String fn(Number a)
* ...
The named parameters defined using @param would not need the type definition in this case, as the signature already has the name and the type defined.
Though in the case of object literals (I haven't yet checked how the object literals are type checked) but I recon the object literal could be easily defined inside named @param, I haven't thoroughly thought out the syntax but something like:
* ...
* @param opts {
* some? String : Give this value if you want,
* other Number : This is required value,
* ...
* }
* @types String fn(objectliteral opts)
* ...
As a side note I want to congratulate the VJET project for creating probably the best and simplest way to type check / semantic checking seen in any IDE for dynamically typed language. In my opinion the type checking must be done in the IDE for dynamically typed languages because there is no compilation phase (if one does not count unit testing as such) to catch the type errors.
|
|
|
| Re: Documenting the parameters and a function? JSDoc again... [message #1016502 is a reply to message #1013408] |
Wed, 06 March 2013 12:02  |
Justin Early
Messages: 12
Registered: June 2012 |
Junior Member |
|
|
Hi Jari,
Thanks for the compliment. I am sorry it took awhile to get back to you. VJETDoc can work along side JSdoc. I have found that a new type declaration is required vs using JSDoc for many reasons outlined here [1] I hope to come up with a good explanation to your question. In your example
/**
* Test
*
* @param a The super number
* @param b The other number
* @param c Something fancy
*/
function test(a, b, c) { // < String test(Number a, Number b, String c)
return (a + b) + "" + c
}
You can combine the two comments such as:
/**> String test(Number a, Number b, String c);
* Test
*
* @param a The super number
* @param b The other number
* @param c Something fancy
*/
function test(a, b, c) {
return (a + b) + "" + c
}
The trick is the semicolon after the vjetdoc signature.
You can also not repeat yourself with vjetdoc. The vjetdoc is positional so you don't need to repeat the a,b,c argument names. Here is an example:
/**> String test(Number, Number, String);
* Test
*
* @param a The super number
* @param b The other number
* @param c Something fancy
*/
function test(a, b, c) {
return (a + b) + "" + c
}
Overloaded case + Js docs
/**
* My js docs
* @param a The date you were born
*/
//> public Date fn(String)
//> private void fn(Date)
function overloaded(a){
return new Date();
}
As far as the @types annotation there are a few challenges.
1. VJETDoc works with every statement, but that doesn't mean jsdoc should not be extended to understand a simpler type signature. VJETDoc would have to differentiate between vjetdoc //> //< /**< comments and annotation (which is possible just a hurdle that would have be overcome)
2. Overloads -- It just gets difficult when there are @return and access annotations (@public,@private,@protected) statements for overloads.
// overloading is a challenge here with jsdoc 2 different access modifiers and different return types based on different argument types.
//> public Date fn(String)
//> private void fn(Date)
function overloaded(a){
return new Date();
}
The @types param would have to be used and other annotations would have to be ignored.
As far as the object literal typing that VJET does
I know that jsduck project from sencha uses a dot notation for params.
/**
* @param {Object} o
@param {Date} o.date
*/
function doIt(o){}
}
My only reservation about this style is that I may want to reference the same object literal type definition multiple times. (they are often reused over and over) and I don't want to redefine this in multiple jsdoc comments.
[1] http://wiki.eclipse.org/VJET/Overview_of_VJETDoc#Type_Declarations_and_VJETDoc
|
|
|
Powered by
FUDForum. Page generated in 0.01568 seconds
] 
Search
Help
Register
Login
Home
