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?

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.

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.

VJET/VJETDoc Quick Reference

Contents

What is VJETDoc?

VJETDoc Syntax

Direction Matters

Escape

Syntax Rules

Type Declaration Examples

JavaScript Types

JavaScript Constructs

Arrays

Multi-Type Declarations

Function Declarations

Modifier Order

Arguments

Overload

Function Assignment

Calling a Function with Another Function as an Argument

A Function Returning a Function

Typing a Function in an Object Literal

Attributed Types

Casting

Breadcrumbs

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.

VJET/VJETDoc Quick Reference

Contents

What is VJETDoc?

VJETDoc Syntax

Direction Matters

Escape

Syntax Rules

Type Declaration Examples

JavaScript Types

JavaScript Constructs

Arrays

Multi-Type Declarations

Function Declarations

Modifier Order

Arguments

Overload

Function Assignment

Calling a Function with Another Function as an Argument

A Function Returning a Function

Typing a Function in an Object Literal

Attributed Types

Casting