Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "VJET/Type Declarations Using VJETDoc"
(→Fix Errors Using Code Proposals From VJETDoc) |
|||
(2 intermediate revisions by the same user not shown) | |||
Line 58: | Line 58: | ||
− | < | + | <source lang="javascript"> |
− | + | ||
//> //< /*> /*< | //> //< /*> /*< | ||
− | </ | + | </source> |
Line 73: | Line 72: | ||
− | < | + | <source lang="javascript"> |
− | + | ||
var dd = new Date(); //<Date | var dd = new Date(); //<Date | ||
− | </ | + | </source> |
− | + | ||
− | + | ||
To annotate a type itself, other than instance of a type, use the '''type::''' qualifier: | To annotate a type itself, other than instance of a type, use the '''type::''' qualifier: | ||
− | + | <source lang="javascript"> | |
− | + | ||
− | + | ||
− | < | + | |
− | + | ||
var D = Date; //<type::Date | var D = Date; //<type::Date | ||
− | </ | + | </source> |
− | + | ||
− | + | ||
Array type can be represented as a generic array or typed array: | Array type can be represented as a generic array or typed array: | ||
− | + | <source lang="javascript"> | |
− | + | ||
− | + | ||
− | < | + | |
− | + | ||
//<Array //<String[] //<int[] | //<Array //<String[] //<int[] | ||
− | </ | + | </source> |
− | + | ||
Variant type (multi-types) can be denoted using | Variant type (multi-types) can be denoted using | ||
− | < | + | <source lang="javascript"> |
− | + | ||
{t1 | {t1 | ||
| t2 | | t2 | ||
| t3} | | t3} | ||
− | </ | + | </source> |
for example, | for example, | ||
− | + | <source lang="javascript"> | |
− | + | ||
− | < | + | |
− | + | ||
//<{String | //<{String | ||
| String[] | | String[] | ||
| Node} | | Node} | ||
− | </ | + | </source> |
− | + | ||
− | + | ||
Function can be represented as: | Function can be represented as: | ||
− | |||
<TYPE> <FN_NAME>() or <TYPE> <FN_NAME> (<ARG> <nowiki>[[</nowiki>,<ARG<nowiki>]]</nowiki>*) | <TYPE> <FN_NAME>() or <TYPE> <FN_NAME> (<ARG> <nowiki>[[</nowiki>,<ARG<nowiki>]]</nowiki>*) | ||
Line 141: | Line 119: | ||
A function can only have one varargs, which also has to be the last arg. If there is one optional arg, any following args have to be optional args or varargs (last). For example, | A function can only have one varargs, which also has to be the last arg. If there is one optional arg, any following args have to be optional args or varargs (last). For example, | ||
− | + | <source lang="javascript"> | |
− | + | ||
− | < | + | |
− | + | ||
function foo(node, copy) {//<String fn({String | function foo(node, copy) {//<String fn({String | ||
| Node}, {String | | Node}, {String | ||
| Node}?) | | Node}?) | ||
} | } | ||
− | </ | + | </source> |
− | + | ||
If a return type or arg type itself is another function declaration, that type has to be surrounded by parentheses, for example, | If a return type or arg type itself is another function declaration, that type has to be surrounded by parentheses, for example, | ||
| | ||
− | + | <source lang="javascript"> | |
− | + | ||
− | < | + | |
− | + | ||
//>(void fn(Date)) fn(String, (int fn(boolean, Node))) | //>(void fn(Date)) fn(String, (int fn(boolean, Node))) | ||
var bar = function(id, callback) { | var bar = function(id, callback) { | ||
} | } | ||
− | </ | + | </source> |
− | + | ||
If a function is overloaded with multiple APIs, multiple VJETDoc statements can be used: | If a function is overloaded with multiple APIs, multiple VJETDoc statements can be used: | ||
− | + | <source lang="javascript"> | |
− | + | ||
− | < | + | |
− | + | ||
//>Object attr({Node | //>Object attr({Node | ||
| String}, String name) | | String}, String name) | ||
Line 179: | Line 146: | ||
function attr(node) { | function attr(node) { | ||
} | } | ||
− | </ | + | </source> |
− | + | ||
− | + | ||
For more advanced syntax, such as function extension with <nowiki>^</nowiki>, type casting with //<< or //>>, generics with <T>, <T extends xxx>, etc., please refer to VJETDoc Reference Guide. For a quick overview refer to the [[VJET:VJETDoc Quick Reference]]. | For more advanced syntax, such as function extension with <nowiki>^</nowiki>, type casting with //<< or //>>, generics with <T>, <T extends xxx>, etc., please refer to VJETDoc Reference Guide. For a quick overview refer to the [[VJET:VJETDoc Quick Reference]]. | ||
[[Category:VJET]] | [[Category:VJET]] | ||
+ | [[Category:VJETDoc]] | ||
+ | [[Category:JavaScript]] |
Latest revision as of 14:00, 5 December 2012
VJETDoc is a form of JavaScript comment syntax used to add type information to JavaScript source code. It differs from JSDoc and JavaDoc as it has comprehensive grammar support to describe the complex semantic API of dynamic JavaScript.
Most importantly, VJETDoc enables the VJET IDE to understand "non-typed" JavaScript code, and is used to provide developers with sophisticated code-assistance, code-completion, and code-validation in the IDE. With VJETDoc, JavaScript developers can precisely type their own API as well as understand those from others.
Contents
VJETDoc Example
The following example illustrates the benefits of using VJETDoc to add type information to JavaScript. Once VJETDoc is added, the VJET JS IDE can validate code based on the type information. Developers can easily fix the errors using code assistance and proposals, again, based on the type information.
The following JavaScript example has a number of errors, but the errors are difficult to detect.
Add VJETDoc to Validate JavaScript
Simply add VJETDoc to the function definition and VJET JS IDE has the information needed to validate the code. Note that VJET JS IDE validates implementation as well as invocation code.
Get Error Details
Hover over the error markers or the underlined text to view error details.
Invalid Arguments
Undefined Function
Wrong Return Type
Fix Errors Using Code Proposals From VJETDoc
Since VJET JS IDE has the type information from VJETDoc, code assist can provide appropriate proposals and assistance.
VJETDoc Basics
VJETDoc grammar is completely defined via extended BNF (Backus-Naur Form) notation. For users who are not familiar with BNF, the following section will partially explain VJETDoc grammar in plain language.
VJETDoc statements start with directional indicator '>' or '<' in the following form,
//> //< /*> /*<
The directional indicator allows you to position the VJETDoc statement before or after its intended source. The '<' indicator applies to the preceding source; the '>' indicator applies to the following source.
Examples
The basic entity in VJETDoc is a "type", such as, String, Number, Date, Function, etc., for example,
var dd = new Date(); //<Date
To annotate a type itself, other than instance of a type, use the type:: qualifier:
var D = Date; //<type::Date
Array type can be represented as a generic array or typed array:
//<Array //<String[] //<int[]
Variant type (multi-types) can be denoted using
{t1 | t2 | t3}
for example,
//<{String | String[] | Node}
Function can be represented as:
<TYPE> <FN_NAME>() or <TYPE> <FN_NAME> (<ARG> [[,<ARG]]*)
<ARG> can be expressed as follows with the arg name being optional,
<TYPE> [[<ARG_NAME>]]
Optional arg is marked with '?',
<TYPE> ? [[<ARG_NAME>]]
Varargs is marked with '...',
<TYPE> ... [[<ARG_NAME>]]
A function can only have one varargs, which also has to be the last arg. If there is one optional arg, any following args have to be optional args or varargs (last). For example,
function foo(node, copy) {//<String fn({String | Node}, {String | Node}?) }
If a return type or arg type itself is another function declaration, that type has to be surrounded by parentheses, for example,
//>(void fn(Date)) fn(String, (int fn(boolean, Node))) var bar = function(id, callback) { }
If a function is overloaded with multiple APIs, multiple VJETDoc statements can be used:
//>Object attr({Node | String}, String name) //>void attr({Node | String}, String name, Object value) //>void attr({Node | String}, ObjLiteral nv) function attr(node) { }
For more advanced syntax, such as function extension with ^, type casting with //<< or //>>, generics with <T>, <T extends xxx>, etc., please refer to VJETDoc Reference Guide. For a quick overview refer to the VJET:VJETDoc Quick Reference.