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/VJETDoc Quick Reference"
(6 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
This document provides a quick, reference style description of basic VJETDoc syntax and usage. This document does not provide in-depth coverage or discuss grammar, usage rules, or concepts. For a detailed discussion of VJETDoc, please refer to the VJETDoc Reference Guide. | This document provides a quick, reference style description of basic VJETDoc syntax and usage. This document does not provide in-depth coverage or discuss grammar, usage rules, or concepts. For a detailed discussion of VJETDoc, please refer to the VJETDoc Reference Guide. | ||
− | |||
− | |||
− | |||
− | |||
= What is VJETDoc? = | = What is VJETDoc? = | ||
Line 10: | Line 6: | ||
VJETDoc ''leverages regular JavaScript comments to provide type information'' about JavaScript constructs. The ability to add type information to JavaScript is a fundamental VJET JS concept. | VJETDoc ''leverages regular JavaScript comments to provide type information'' about JavaScript constructs. The ability to add type information to JavaScript is a fundamental VJET JS concept. | ||
− | |||
− | |||
= VJETDoc Syntax = | = VJETDoc Syntax = | ||
VJETDoc take the form of traditional JavaScript comments, followed by a directional indicator (> or <). The indicator points to the statement to which the VJETDoc applies. The '<' indicator applies to the preceding statement; the '>' indicator points to the following statement. | VJETDoc take the form of traditional JavaScript comments, followed by a directional indicator (> or <). The indicator points to the statement to which the VJETDoc applies. The '<' indicator applies to the preceding statement; the '>' indicator points to the following statement. | ||
− | |||
− | |||
− | |||
− | |||
<source lang="javascript"> | <source lang="javascript"> | ||
Line 36: | Line 26: | ||
In VJETDoc, the < (less-than) and > (greater-than) signs constitute the first character of a JavaScript comment. The meaning of the arrows (< and >) denote the ''direction'' of the JavaScript construct to which the VJETDoc applies. | In VJETDoc, the < (less-than) and > (greater-than) signs constitute the first character of a JavaScript comment. The meaning of the arrows (< and >) denote the ''direction'' of the JavaScript construct to which the VJETDoc applies. | ||
− | + | * A comment starting with "//>" or "/'''<nowiki>'''</nowiki>'''>" or "/**>" means the comment declaration applies to the ''next'' JavaScript entity. | |
− | + | * A comment starting with "//<" or "/<nowiki>*</nowiki><" or "/**<" means the comment applies to the ''previous'' JavaScript entity. | |
− | We support the /<nowiki> | + | We support the /<nowiki>*</nowiki>> ... <nowiki>*</nowiki>/ and /<nowiki>*</nowiki>< ... <nowiki>*</nowiki>/ style comments for systems that treat them as JsDoc-style comments. |
=== Escape === | === Escape === | ||
If you need to escape the directional indicator, you can use any character; we recommend an exclamation mark (<nowiki>!</nowiki>). | If you need to escape the directional indicator, you can use any character; we recommend an exclamation mark (<nowiki>!</nowiki>). | ||
− | |||
− | |||
<source lang="javascript"> | <source lang="javascript"> | ||
Line 52: | Line 40: | ||
//!<html> | //!<html> | ||
</source> | </source> | ||
− | |||
− | |||
− | |||
== Syntax Rules == | == Syntax Rules == | ||
− | * When used with documentation comments, use a semi-colon | + | * When used with documentation comments, use a semi-colon (<nowiki>;</nowiki>) to delineate the type declaration from the documentation text. Documentation comments must appear ''after'' the type declaration. |
− | + | ||
− | + | ||
<source lang="javascript"> | <source lang="javascript"> | ||
var x = 10 ; //< int ; This is a documentation commen | var x = 10 ; //< int ; This is a documentation commen | ||
</source> | </source> | ||
− | |||
− | |||
− | |||
= Type Declaration Examples = | = Type Declaration Examples = | ||
Line 75: | Line 55: | ||
== JavaScript Types == | == JavaScript Types == | ||
− | + | {| style="background-color:#F9F9F9;border:1px solid #AAAAAA;border-collapse:collapse;color:black; margin:1em 0;" | |
− | {| | + | |- |
− | + | ! style="background-color:#F2F2F2;text-align:center;border:1px solid #AAAAAA;padding:0.2em;" | Type | |
− | + | ! style="background-color:#F2F2F2;text-align:center;border:1px solid #AAAAAA;padding:0.2em;" | Example | |
− | + | ||
|- | |- | ||
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | Object |
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | <source lang="javascript"> |
− | + | ||
− | + | ||
− | + | ||
− | <source lang="javascript"> | + | |
var obj1 = new Object() ; //< Object | var obj1 = new Object() ; //< Object | ||
var obj2 = { } ; //< ObjLiteral; This is a synthesized type for representing object literals | var obj2 = { } ; //< ObjLiteral; This is a synthesized type for representing object literals | ||
</source> | </source> | ||
+ | |||
|- | |- | ||
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | Boolean and boolean |
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | <source lang="javascript"> |
− | + | ||
− | <source lang="javascript"> | + | |
var t = true ; //< boolean | var t = true ; //< boolean | ||
var f = false ;//< boolean | var f = false ;//< boolean | ||
Line 102: | Line 77: | ||
var F = new Boolean(false) ; //< Boolean | var F = new Boolean(false) ; //< Boolean | ||
</source> | </source> | ||
− | + | ||
|- | |- | ||
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | Number |
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | <source lang="javascript"> |
− | + | ||
− | <source lang="javascript"> | + | |
var max = 10 ; //< Number | var max = 10 ; //< Number | ||
var boil = 212.0 //< Number | var boil = 212.0 //< Number | ||
Line 117: | Line 90: | ||
var rate = 31.45 ;//< double | var rate = 31.45 ;//< double | ||
</source> | </source> | ||
− | + | ||
|- | |- | ||
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | String |
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | <source lang="javascript"> |
− | + | ||
− | <source lang="javascript"> | + | |
var name = 'MrP' ; //< String | var name = 'MrP' ; //< String | ||
var name2 = new String('MrP') ; //< String | var name2 = new String('MrP') ; //< String | ||
Line 129: | Line 100: | ||
var achar = 'f'; //< char | var achar = 'f'; //< char | ||
</source> | </source> | ||
− | + | ||
|- | |- | ||
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | Date |
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | <source lang="javascript"> |
− | + | ||
− | <source lang="javascript"> | + | |
var today = new Date() ; //< Date | var today = new Date() ; //< Date | ||
</source> | </source> | ||
− | + | ||
|- | |- | ||
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | Function |
− | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | <source lang="javascript"> | |
− | <source lang="javascript"> | + | |
function add(a, b) { //< Number add(Number, Number) | function add(a, b) { //< Number add(Number, Number) | ||
return a + b ; | return a + b ; | ||
Line 151: | Line 119: | ||
} | } | ||
</source> | </source> | ||
− | + | ||
|- | |- | ||
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | Array |
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | <source lang="javascript"> |
− | + | ||
− | <source lang="javascript"> | + | |
var names1 = ['Adams', 'Jefferson', 'Wilson'] ; //< Array | var names1 = ['Adams', 'Jefferson', 'Wilson'] ; //< Array | ||
Line 164: | Line 130: | ||
names2[2] = 'Wilson' ; | names2[2] = 'Wilson' ; | ||
</source> | </source> | ||
− | |||
+ | |} | ||
== JavaScript Constructs == | == JavaScript Constructs == | ||
− | + | {| style="background-color:#F9F9F9;border:1px solid #AAAAAA;border-collapse:collapse;color:black; margin:1em 0;" | |
− | {| | + | |- |
− | + | ! style="background-color:#F2F2F2;text-align:center;border:1px solid #AAAAAA;padding:0.2em;" | Construct | |
− | + | ! style="background-color:#F2F2F2;text-align:center;border:1px solid #AAAAAA;padding:0.2em;" | Example | |
− | + | ||
|- | |- | ||
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | Global Variables |
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | <source lang="javascript"> |
− | | | + | |
− | + | ||
− | + | ||
− | + | ||
− | <source lang="javascript"> | + | |
Counter = 10 ; //< Number | Counter = 10 ; //< Number | ||
</source> | </source> | ||
− | + | ||
|- | |- | ||
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | Local Variables |
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | <source lang="javascript"> |
− | + | ||
− | <source lang="javascript"> | + | |
var id = 'AX123' ; //< String | var id = 'AX123' ; //< String | ||
</source> | </source> | ||
− | + | ||
|- | |- | ||
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | Object Literals |
− | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | <source lang="javascript"> | |
− | <source lang="javascript"> | + | |
var person = { | var person = { | ||
name: 'MrP', //< String | name: 'MrP', //< String | ||
Line 206: | Line 164: | ||
} | } | ||
</source> | </source> | ||
− | + | ||
|- | |- | ||
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | Object Properties |
− | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | <source lang="javascript"> | |
− | <source lang="javascript"> | + | |
var person = new Object ; | var person = new Object ; | ||
person.name = 'MrP'; //< String | person.name = 'MrP'; //< String | ||
Line 220: | Line 177: | ||
} | } | ||
</source> | </source> | ||
− | + | ||
|- | |- | ||
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | Type References |
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | <source lang="javascript"> |
− | + | ||
− | <source lang="javascript"> | + | |
var theDateType = Date ; < type::Date | var theDateType = Date ; < type::Date | ||
var today = new theDateType ; < Date | var today = new theDateType ; < Date | ||
</source> | </source> | ||
− | + | ||
|- | |- | ||
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | Function Expressions |
− | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | <source lang="javascript"> | |
− | <source lang="javascript"> | + | |
function max(a, b) {//< void max(String, Date) | function max(a, b) {//< void max(String, Date) | ||
} | } | ||
var func = new Function("a", "vjo.sysout.println(a)");//< void fn(String) | var func = new Function("a", "vjo.sysout.println(a)");//< void fn(String) | ||
</source> | </source> | ||
− | + | ||
|- | |- | ||
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | Function References |
− | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" |<source lang="javascript"> | |
− | <source lang="javascript"> | + | |
var f = function(a, b) { ... } //< void fn(String,String) | var f = function(a, b) { ... } //< void fn(String,String) | ||
var f = new Function('a', 'b', '...') //< void fn(String, Date) | var f = new Function('a', 'b', '...') //< void fn(String, Date) | ||
</source> | </source> | ||
− | + | ||
|- | |- | ||
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | Statements |
− | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" |<source lang="javascript"> | |
− | <source lang="javascript"> | + | |
// The for-loop and for...in statements have variables that are part of the construct. | // The for-loop and for...in statements have variables that are part of the construct. | ||
// Those variables can be typed | // Those variables can be typed | ||
Line 262: | Line 214: | ||
} | } | ||
</source> | </source> | ||
− | + | ||
+ | |} | ||
+ | |||
== Arrays == | == Arrays == | ||
− | + | {| style="background-color:#F9F9F9;border:1px solid #AAAAAA;border-collapse:collapse;color:black; margin:1em 0;" | |
− | {| | + | |- |
− | + | ! style="background-color:#F2F2F2;text-align:center;border:1px solid #AAAAAA;padding:0.2em;" | | |
− | + | ! style="background-color:#F2F2F2;text-align:center;border:1px solid #AAAAAA;padding:0.2em;" | Example | |
− | + | ||
|- | |- | ||
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | Array Type |
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | <source lang="javascript"> |
− | | | + | |
− | + | ||
− | + | ||
− | + | ||
− | <source lang="javascript"> | + | |
var browsers = ['Firefox', 'Chrome', 'Safari'] ; //< Array | var browsers = ['Firefox', 'Chrome', 'Safari'] ; //< Array | ||
Line 288: | Line 237: | ||
browsers[2] = 'Safari' ; | browsers[2] = 'Safari' ; | ||
</source> | </source> | ||
− | + | ||
|- | |- | ||
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | Type of Array |
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | <source lang="javascript"> |
− | + | ||
− | <source lang="javascript"> | + | |
var scores = [91, 77, 84] ; //< Number[] | var scores = [91, 77, 84] ; //< Number[] | ||
var names = ['Mark', 'Sean', 'Juan'] ; //< String[] | var names = ['Mark', 'Sean', 'Juan'] ; //< String[] | ||
Line 299: | Line 246: | ||
scores[3] = 12 ; | scores[3] = 12 ; | ||
</source> | </source> | ||
− | + | ||
|- | |- | ||
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | Two Dimensional Array |
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | <source lang="javascript"> |
− | + | ||
− | <source lang="javascript"> | + | |
var keys = [ //< Number[][] | var keys = [ //< Number[][] | ||
[1, 2, 3], | [1, 2, 3], | ||
Line 311: | Line 256: | ||
]; | ]; | ||
</source> | </source> | ||
− | + | ||
+ | |} | ||
Line 318: | Line 264: | ||
VJETDoc supports the notion of a single argument having more than one valid type. | VJETDoc supports the notion of a single argument having more than one valid type. | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | + | {| style="background-color:#F9F9F9;border:1px solid #AAAAAA;border-collapse:collapse;color:black; margin:1em 0;" | |
+ | |- | ||
+ | ! style="background-color:#F2F2F2;text-align:center;border:1px solid #AAAAAA;padding:0.2em;" | | ||
+ | ! style="background-color:#F2F2F2;text-align:center;border:1px solid #AAAAAA;padding:0.2em;" | Example | ||
− | <source lang="javascript"> | + | |- |
+ | | style="border:1px solid #AAAAAA;padding: 0.2em;" | Variable multi-type | ||
+ | | style="border:1px solid #AAAAAA;padding: 0.2em;" | <source lang="javascript"> | ||
var x = 10 ; //< {int String} | var x = 10 ; //< {int String} | ||
</source> | </source> | ||
− | + | ||
|- | |- | ||
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | Function argument multi-type |
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | <source lang="javascript"> |
− | + | ||
− | <source lang="javascript"> | + | |
//> void foo({int String}) | //> void foo({int String}) | ||
foo : function(x) { | foo : function(x) { | ||
} | } | ||
</source> | </source> | ||
− | |||
+ | |} | ||
== Function Declarations == | == Function Declarations == | ||
Line 351: | Line 291: | ||
=== Modifier Order === | === Modifier Order === | ||
+ | {| style="background-color:#F9F9F9;border:1px solid #AAAAAA;border-collapse:collapse;color:black; margin:1em 0;" | ||
+ | |- | ||
+ | ! style="background-color:#F2F2F2;text-align:center;border:1px solid #AAAAAA;padding:0.2em;" | Example | ||
+ | ! style="background-color:#F2F2F2;text-align:center;border:1px solid #AAAAAA;padding:0.2em;" | Description | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
|- | |- | ||
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | <source lang="javascript"> foo : function() //< void |
− | | | + | foo : function() //< void |
+ | foo : function() //< void f1(String) | ||
+ | </source> | ||
+ | | style="border:1px solid #AAAAAA;padding: 0.2em;" | Return type is mandatory; access modifier is optional. Function name is not required unless function description includes arguments. <br/> | ||
+ | The function name doesn't need to match the actual function name. | ||
− | |||
− | |||
− | |||
− | |||
− | |||
|- | |- | ||
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | <source lang="javascript"> foo : function() //< final void |
− | foo : function() //< final void < | + | foo : function() //< final void |
− | | | + | </source> |
+ | | style="border:1px solid #AAAAAA;padding: 0.2em;" | ''final'' is optional, but if used, appears before the return type | ||
+ | |||
+ | |} | ||
=== Arguments === | === Arguments === | ||
− | + | {| style="background-color:#F9F9F9;border:1px solid #AAAAAA;border-collapse:collapse;color:black; margin:1em 0;" | |
− | + | |- | |
− | {| | + | ! style="background-color:#F2F2F2;text-align:center;border:1px solid #AAAAAA;padding:0.2em;" | Function Arguments |
− | + | ! style="background-color:#F2F2F2;text-align:center;border:1px solid #AAAAAA;padding:0.2em;" | Example | |
− | + | ! style="background-color:#F2F2F2;text-align:center;border:1px solid #AAAAAA;padding:0.2em;" | Notes | |
− | + | ||
|- | |- | ||
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | No Arguments |
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" |<source lang="javascript"> |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | <source lang="javascript"> | + | |
foo : function() { //< void | foo : function() { //< void | ||
} | } | ||
</source> | </source> | ||
− | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | If a function takes no arguments, a function signature is not required | |
− | | | + | |
|- | |- | ||
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | Single Argument |
− | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" |<source lang="javascript"> | |
− | <source lang="javascript"> | + | |
foo : function(x) { //< void foo(int x) | foo : function(x) { //< void foo(int x) | ||
} | } | ||
</source> | </source> | ||
− | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | | |
− | | | + | |
|- | |- | ||
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | Multiple Arguments |
− | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" |<source lang="javascript"> | |
− | <source lang="javascript"> | + | |
foo : function(x, y) { //< void foo(Number x, Function y) | foo : function(x, y) { //< void foo(Number x, Function y) | ||
} | } | ||
</source> | </source> | ||
− | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | | |
− | | | + | |
|- | |- | ||
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | Multi-type Arguments |
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" |<source lang="javascript"> |
− | + | ||
− | <source lang="javascript"> | + | |
//> void f({int String}) | //> void f({int String}) | ||
foo : function(x){ | foo : function(x){ | ||
} | } | ||
</source> | </source> | ||
− | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | VJETDoc supports the notion of a single argument having more than one valid type. In the example, the argument can be either an int or a String. | |
− | | | + | |
|- | |- | ||
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | Optional Argument |
− | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" |<source lang="javascript"> | |
− | <source lang="javascript"> | + | |
foo : function(x) { //< void foo(int? x) | foo : function(x) { //< void foo(int? x) | ||
} | } | ||
Line 432: | Line 361: | ||
} | } | ||
</source> | </source> | ||
− | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | Optional arguments are specified with a question mark ('''?''') | |
− | | | + | |
|- | |- | ||
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | Variable Argument |
− | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" |<source lang="javascript"> | |
− | <source lang="javascript"> | + | |
foo : function(args) { //< void foo(String... args) { | foo : function(args) { //< void foo(String... args) { | ||
} | } | ||
Line 444: | Line 372: | ||
} | } | ||
</source> | </source> | ||
− | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | Variable arguments are specified with ellipsis ('''...''') | |
− | | | + | |
|- | |- | ||
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | Typed Function Argument |
− | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" |<source lang="javascript"> | |
− | <source lang="javascript"> | + | |
//> void dateProvider( (void f(Date)) needsAdate) | //> void dateProvider( (void f(Date)) needsAdate) | ||
function dateProvider(needsAdate) { | function dateProvider(needsAdate) { | ||
Line 455: | Line 382: | ||
} | } | ||
</source> | </source> | ||
− | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | | |
− | | | + | |
+ | |} | ||
=== Overload === | === Overload === | ||
− | + | {| style="background-color:#F9F9F9;border:1px solid #AAAAAA;border-collapse:collapse;color:black; margin:1em 0;" | |
− | {| | + | |- |
− | + | ! style="background-color:#F2F2F2;text-align:center;border:1px solid #AAAAAA;padding:0.2em;" | | |
− | + | ! style="background-color:#F2F2F2;text-align:center;border:1px solid #AAAAAA;padding:0.2em;" | Example | |
− | + | ||
|- | |- | ||
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | Overload |
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | <source lang="javascript"> |
− | | | + | |
− | + | ||
− | + | ||
− | + | ||
− | <source lang="javascript"> | + | |
//> void f() | //> void f() | ||
//> void f(int) | //> void f(int) | ||
Line 478: | Line 401: | ||
foo : f() | foo : f() | ||
</source> | </source> | ||
− | + | ||
|- | |- | ||
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | Overload with vararg |
− | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | <source lang="javascript"> | |
− | <source lang="javascript"> | + | |
//> void g(int?, String?) | //> void g(int?, String?) | ||
function g() { } | function g() { } | ||
</source> | </source> | ||
− | + | ||
|- | |- | ||
− | | Overload with different return types | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | Overload with different return types |
− | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | <source lang="javascript"> | |
− | <source lang="javascript"> | + | |
//> Number add(Number, Number) | //> Number add(Number, Number) | ||
//> String add(String, String) | //> String add(String, String) | ||
Line 496: | Line 417: | ||
return a + b ; } | return a + b ; } | ||
</source> | </source> | ||
− | + | ||
+ | |} | ||
=== Function Assignment === | === Function Assignment === | ||
− | |||
− | |||
<source lang="javascript"> | <source lang="javascript"> | ||
Line 514: | Line 434: | ||
=== Calling a Function with Another Function as an Argument === | === Calling a Function with Another Function as an Argument === | ||
− | |||
− | |||
<source lang="javascript"> | <source lang="javascript"> | ||
Line 551: | Line 469: | ||
); | ); | ||
</source> | </source> | ||
− | |||
− | |||
=== A Function Returning a Function === | === A Function Returning a Function === | ||
We can type the return type of a function with VJETDoc | We can type the return type of a function with VJETDoc | ||
− | |||
− | |||
<source lang="javascript"> | <source lang="javascript"> | ||
Line 575: | Line 489: | ||
var mymaxer10 = maxer(10) ; //< boolean f(int) | var mymaxer10 = maxer(10) ; //< boolean f(int) | ||
</source> | </source> | ||
− | |||
− | |||
=== Typing a Function in an Object Literal === | === Typing a Function in an Object Literal === | ||
A function can be assigned to the member name in an Object Literal. Since the member name is the actual function name, we use the function expression syntax. | A function can be assigned to the member name in an Object Literal. Since the member name is the actual function name, we use the function expression syntax. | ||
− | |||
− | |||
<source lang="javascript"> | <source lang="javascript"> | ||
Line 604: | Line 514: | ||
By VJET types, we mean ctype, etype, mtype, itype,fytpe and mtype. | By VJET types, we mean ctype, etype, mtype, itype,fytpe and mtype. | ||
− | + | {| style="background-color:#F9F9F9;border:1px solid #AAAAAA;border-collapse:collapse;color:black; margin:1em 0;" | |
− | {| | + | |- |
− | + | ! style="background-color:#F2F2F2;text-align:center;border:1px solid #AAAAAA;padding:0.2em;" | Example | |
− | + | ! style="background-color:#F2F2F2;text-align:center;border:1px solid #AAAAAA;padding:0.2em;" | Notes | |
− | + | ||
|- | |- | ||
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" |<source lang="javascript">var x ; //< ::addEventListener |
− | | | + | </source> |
− | |} | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | |
+ | |||
+ | |} | ||
− | |||
== Casting == | == Casting == | ||
Use 2 directional indicators ('''//<<,''' *//>>*) to indicate a cast. | Use 2 directional indicators ('''//<<,''' *//>>*) to indicate a cast. | ||
− | + | {| style="background-color:#F9F9F9;border:1px solid #AAAAAA;border-collapse:collapse;color:black; margin:1em 0;" | |
− | {| | + | |- |
− | + | ! style="background-color:#F2F2F2;text-align:center;border:1px solid #AAAAAA;padding:0.2em;" | Example | |
− | + | ! style="background-color:#F2F2F2;text-align:center;border:1px solid #AAAAAA;padding:0.2em;" | Notes | |
− | + | ||
|- | |- | ||
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" |<source lang="javascript"> |
− | | | + | var person2 = PFactory.create('MrP', 30) //<< Person</source> |
+ | | style="border:1px solid #AAAAAA;padding: 0.2em;" | Assignment cast | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
|- | |- | ||
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" |<source lang="javascript"> |
− | + | ||
− | <source lang="javascript"> | + | |
var x ; //< X | var x ; //< X | ||
x = create() ; //<< ; cast create() to type X</source> | x = create() ; //<< ; cast create() to type X</source> | ||
− | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | If the type of the left-hand side of the assignment is known, a shorthand cast can be used by leaving out the type name | |
− | | | + | |
|- | |- | ||
− | | | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" |<source lang="javascript"> |
− | + | ||
− | <source lang="javascript"> | + | |
var d = something() ; | var d = something() ; | ||
//<< Date ; this doubles as declaration and cast of something() | //<< Date ; this doubles as declaration and cast of something() | ||
</source> | </source> | ||
− | + | | style="border:1px solid #AAAAAA;padding: 0.2em;" | If the variable type is not known, the cast operation can do double duty by typing and casting. | |
− | | If the variable type is not known, the cast operation can do double duty by typing and casting. | + | |
+ | |} | ||
+ | |||
[[Category:VJET]] | [[Category:VJET]] | ||
[[Category:VJETDoc]] | [[Category:VJETDoc]] | ||
[[Category:JavaScript]] | [[Category:JavaScript]] |
Latest revision as of 23:53, 5 December 2012
This document provides a quick, reference style description of basic VJETDoc syntax and usage. This document does not provide in-depth coverage or discuss grammar, usage rules, or concepts. For a detailed discussion of VJETDoc, please refer to the VJETDoc Reference Guide.
Contents
What is VJETDoc?
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.
VJETDoc leverages regular JavaScript comments to provide type information about JavaScript constructs. The ability to add type information to JavaScript is a fundamental VJET JS concept.
VJETDoc Syntax
VJETDoc take the form of traditional JavaScript comments, followed by a directional indicator (> or <). The indicator points to the statement to which the VJETDoc applies. The '<' indicator applies to the preceding statement; the '>' indicator points to the following statement.
var d = 10 ; //< int //> int var d = 10 ; getRate : function(int x) { /*< int getRate(int x) */ ... }
Direction Matters
In VJETDoc, the < (less-than) and > (greater-than) signs constitute the first character of a JavaScript comment. The meaning of the arrows (< and >) denote the direction of the JavaScript construct to which the VJETDoc applies.
- A comment starting with "//>" or "/'''>" or "/**>" means the comment declaration applies to the next JavaScript entity.
- A comment starting with "//<" or "/*<" or "/**<" means the comment applies to the previous JavaScript entity.
We support the /*> ... */ and /*< ... */ style comments for systems that treat them as JsDoc-style comments.
Escape
If you need to escape the directional indicator, you can use any character; we recommend an exclamation mark (!).
//<html> //!<html>
Syntax Rules
- When used with documentation comments, use a semi-colon (;) to delineate the type declaration from the documentation text. Documentation comments must appear after the type declaration.
var x = 10 ; //< int ; This is a documentation commen
Type Declaration Examples
JavaScript Types
Type | Example |
---|---|
Object | var obj1 = new Object() ; //< Object var obj2 = { } ; //< ObjLiteral; This is a synthesized type for representing object literals
|
Boolean and boolean | var t = true ; //< boolean var f = false ;//< boolean var T = new Boolean(true) ; //< Boolean var F = new Boolean(false) ; //< Boolean |
Number | var max = 10 ; //< Number var boil = 212.0 //< Number var rate = 31.45 ;//< Number // the following types are synthesized and all extend Number: int, short, long, float, double ==> JavaScript Number var max= 10;//< int var boil= 31.45 ;//< float var rate = 31.45 ;//< double |
String | var name = 'MrP' ; //< String var name2 = new String('MrP') ; //< String // the following type char is synthesized and extends String var achar = 'f'; //< char |
Date | var today = new Date() ; //< Date |
Function | function add(a, b) { //< Number add(Number, Number) return a + b ; } //> Number add(Number, Number) ; function expression function(a, b) { return a + b ; } |
Array | var names1 = ['Adams', 'Jefferson', 'Wilson'] ; //< Array var names2 = new Array() ; //< Array names2[0] = 'Adams' ; names2[1] = 'Jefferson' ; names2[2] = 'Wilson' ; |
JavaScript Constructs
Construct | Example |
---|---|
Global Variables | Counter = 10 ; //< Number |
Local Variables | var id = 'AX123' ; //< String |
Object Literals | var person = { name: 'MrP', //< String age: 33, //< int bday: undefined, //< Date married: true //< boolean isRated: function(){ //< Function return true ;} } |
Object Properties | var person = new Object ; person.name = 'MrP'; //< String person.age = 33 ; //< int person.bday = undefined ; //< Date person.married = true ; //< boolean person.isRated = function() { //< Function return true ; } } |
Type References | var theDateType = Date ; < type::Date var today = new theDateType ; < Date |
Function Expressions | function max(a, b) {//< void max(String, Date) } var func = new Function("a", "vjo.sysout.println(a)");//< void fn(String) |
Function References | var f = function(a, b) { ... } //< void fn(String,String) var f = new Function('a', 'b', '...') //< void fn(String, Date) |
Statements | // The for-loop and for...in statements have variables that are part of the construct. // Those variables can be typed for(var i=0;/*<Number*/ i<10;i++){ } // for..in loops through the elements of an Array or through the Properties of an Object. // This doesn't require a type comment since variable here will always be treated as a String for (var variable in someObject) { } |
Arrays
Example | |
---|---|
Array Type | var browsers = ['Firefox', 'Chrome', 'Safari'] ; //< Array var browsers = new Array('Firefox', 'Chrome', 'Safari') ; //< Array var browsers = new Array() ; //< Array browsers[0] = 'FireFox' ; browsers[1] = 'Chrome' ; browsers[2] = 'Safari' ; |
Type of Array | var scores = [91, 77, 84] ; //< Number[] var names = ['Mark', 'Sean', 'Juan'] ; //< String[] names[3] = 'Justin' ; scores[3] = 12 ; |
Two Dimensional Array | var keys = [ //< Number[][] [1, 2, 3], [4, 5, 6], [7, 8, 9] ]; |
Multi-Type Declarations
VJETDoc supports the notion of a single argument having more than one valid type.
Example | |
---|---|
Variable multi-type | var x = 10 ; //< {int String} |
Function argument multi-type | //> void foo({int String}) foo : function(x) { } |
Function Declarations
Modifier Order
Example | Description |
---|---|
foo : function() //< void foo : function() //< void foo : function() //< void f1(String) |
Return type is mandatory; access modifier is optional. Function name is not required unless function description includes arguments. The function name doesn't need to match the actual function name. |
foo : function() //< final void foo : function() //< final void |
final is optional, but if used, appears before the return type |
Arguments
Function Arguments | Example | Notes |
---|---|---|
No Arguments | foo : function() { //< void } |
If a function takes no arguments, a function signature is not required |
Single Argument | foo : function(x) { //< void foo(int x) } |
|
Multiple Arguments | foo : function(x, y) { //< void foo(Number x, Function y) } |
|
Multi-type Arguments | //> void f({int String}) foo : function(x){ } |
VJETDoc supports the notion of a single argument having more than one valid type. In the example, the argument can be either an int or a String. |
Optional Argument | foo : function(x) { //< void foo(int? x) } //> void foo(int x, int? y)foo : function(x, y) { } |
Optional arguments are specified with a question mark (?) |
Variable Argument | foo : function(args) { //< void foo(String... args) { } //> void foo(int x, String... args)foo : function(x, args) { } |
Variable arguments are specified with ellipsis (...) |
Typed Function Argument | //> void dateProvider( (void f(Date)) needsAdate) function dateProvider(needsAdate) { needsAdate(new Date) ; } |
Overload
Example | |
---|---|
Overload | //> void f() //> void f(int) //> void f(String) foo : f() |
Overload with vararg | //> void g(int?, String?) function g() { } |
Overload with different return types | //> Number add(Number, Number) //> String add(String, String) function add(a, b){ return a + b ; } |
Function Assignment
var max ; //< Number max(Number a, Number b) function f(a, b) { //< Number max(Number, Number) return (a > b) ? a : b ; } max = f ; // should be ok since function signatures are compatible
Calling a Function with Another Function as an Argument
//> void dateProvider( (void f(Date)) needsAdate) function dateProvider(needsAdate) { needsAdate(new Date) ; } //> void sayDateDay(Date date) function sayDateDay(date) { var day = date.getDay() ; } var sayDateDay2 = sayDateDay ; //< void sayDate(Date date) // We will now call dateProvider with: // 1. Our declared function sayDate // 2. Our function assigned to a local variable sayDate2 // 3. A function expression using keywork function // 4. A function expression using the Function constructor dateProvider(sayDateDay) ; // declared function dateProvider(sayDateDay2) ;// function from local variable dateProvider( // function expression from function keyword //> void function(Date date) function(date){ var day = date.getDay() ; } ); dateProvider( // function expression from Function constructor //> void function(Date date) new Function( 'date', 'var day = date.getDay() ; ') );
A Function Returning a Function
We can type the return type of a function with VJETDoc
/*> (boolean f(int)) maxer(int max) ; * Our function generator will return a function that will return * true if the passed in value is greater than max, else returns false */ function maxer(max) { //> boolean f(int) ; this is the function we return function f(value) { var mymax = max ; //< int return value > mymax ; } return f; } var mymaxer10 = maxer(10) ; //< boolean f(int)
Typing a Function in an Object Literal
A function can be assigned to the member name in an Object Literal. Since the member name is the actual function name, we use the function expression syntax.
var contract = { rate: 22.45, //< Number location: 'Boston', //< String open: true, //< boolean //> boolean isCostly() isCostly: function(){ return this.rate > 30.00 ; } } var costly = contract.isCostly() ; //< boolean
Attributed Types
The idea of attributed types is that we would like to be able to refer to a type that has already been assigned to another Vjet type's member.
By VJET types, we mean ctype, etype, mtype, itype,fytpe and mtype.
Example | Notes |
---|---|
var x ; //< ::addEventListener |
Casting
Use 2 directional indicators (//<<, *//>>*) to indicate a cast.
Example | Notes |
---|---|
var person2 = PFactory.create('MrP', 30) //<< Person |
Assignment cast |
var x ; //< X x = create() ; //<< ; cast create() to type X |
If the type of the left-hand side of the assignment is known, a shorthand cast can be used by leaving out the type name |
var d = something() ; //<< Date ; this doubles as declaration and cast of something() |
If the variable type is not known, the cast operation can do double duty by typing and casting. |