View source for VJET/VJETDoc Quick Reference

This document provides a quick, reference style description of basic VJETDoc syntax and usage.&nbsp; This document does not provide in-depth coverage or discuss grammar, usage rules, or concepts.&nbsp; 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.&nbsp; 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.&nbsp; The '<' indicator applies to the preceding statement; the '>' indicator points to the following statement.

<source lang="javascript">
var d = 10 ; //< int

//> int
var d = 10 ;

getRate : function(int x) { /*< int getRate(int x) */
  ...
}
</source>


=== Direction Matters ===

In VJETDoc, the < (less-than) and > (greater-than) signs constitute the first character of a JavaScript comment.&nbsp; 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>*</nowiki>> ... <nowiki>*</nowiki>/  and /<nowiki>*</nowiki>< ... <nowiki>*</nowiki>/ 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 (<nowiki>!</nowiki>).

<source lang="javascript">
//<html>

//!<html>
</source>

== Syntax Rules ==


* 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">
var x = 10 ; //< int ; This is a documentation commen
</source>

= Type Declaration Examples =


== 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">
var obj1 = new Object() ;  //< Object
var obj2 = { } ; //< ObjLiteral; This is a synthesized type for representing object literals
</source>

 
|-
| style="border:1px solid #AAAAAA;padding: 0.2em;" |   Boolean and boolean 
| style="border:1px solid #AAAAAA;padding: 0.2em;" | <source lang="javascript">
var t = true ;  //< boolean
var f = false ;//< boolean

var T = new Boolean(true) ;  //< Boolean
var F = new Boolean(false) ; //< Boolean
</source>

|-
| style="border:1px solid #AAAAAA;padding: 0.2em;" |   Number 
| style="border:1px solid #AAAAAA;padding: 0.2em;" | <source lang="javascript">
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
</source>

|-
| style="border:1px solid #AAAAAA;padding: 0.2em;" |   String 
| style="border:1px solid #AAAAAA;padding: 0.2em;" | <source lang="javascript">
var name = 'MrP' ;  //< String
var name2 = new String('MrP') ; //< String

// the following type char is synthesized and extends String
var achar = 'f'; //< char
</source>

|-
| style="border:1px solid #AAAAAA;padding: 0.2em;" |   Date 
| style="border:1px solid #AAAAAA;padding: 0.2em;" | <source lang="javascript">
var today = new Date() ;  //< Date
</source>

|-
| style="border:1px solid #AAAAAA;padding: 0.2em;" |   Function 
| style="border:1px solid #AAAAAA;padding: 0.2em;" | <source lang="javascript">
function add(a, b) {  //< Number add(Number, Number)
    return a + b ;
}

//> Number add(Number, Number) ; function expression
function(a, b) {
    return a + b ;
}
</source>

|-
| style="border:1px solid #AAAAAA;padding: 0.2em;" |   Array 
| style="border:1px solid #AAAAAA;padding: 0.2em;" | <source lang="javascript">
var names1 = ['Adams', 'Jefferson', 'Wilson'] ; //< Array

var names2 = new Array() ; //< Array
names2[0] = 'Adams' ;
names2[1] = 'Jefferson' ;
names2[2] = 'Wilson' ;
</source>

|}

== 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">
Counter = 10 ;  //< Number
</source>

|-
| style="border:1px solid #AAAAAA;padding: 0.2em;" | Local Variables 
| style="border:1px solid #AAAAAA;padding: 0.2em;" | <source lang="javascript">
var id = 'AX123' ; //< String
</source>

|-
| style="border:1px solid #AAAAAA;padding: 0.2em;" | Object Literals 
| style="border:1px solid #AAAAAA;padding: 0.2em;" | <source lang="javascript">
var person = {
name: 'MrP', //< String
age: 33, //< int
bday: undefined, //< Date
married: true //< boolean
isRated: function(){ //< Function
    return true ;}
}
</source>

|-
| style="border:1px solid #AAAAAA;padding: 0.2em;" | Object Properties 
| style="border:1px solid #AAAAAA;padding: 0.2em;" | <source lang="javascript">
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 ; }
}
</source>

|-
| style="border:1px solid #AAAAAA;padding: 0.2em;" | Type References 
| style="border:1px solid #AAAAAA;padding: 0.2em;" | <source lang="javascript">
var theDateType = Date ; < type::Date
var today = new theDateType ; < Date
</source>

|-
| style="border:1px solid #AAAAAA;padding: 0.2em;" | Function Expressions 
| style="border:1px solid #AAAAAA;padding: 0.2em;" | <source lang="javascript">
function max(a, b) {//< void max(String, Date)
}
var func = new Function("a", "vjo.sysout.println(a)");//< void fn(String)
</source>

|-
| style="border:1px solid #AAAAAA;padding: 0.2em;" | Function References 
| style="border:1px solid #AAAAAA;padding: 0.2em;" |<source lang="javascript">
var f = function(a, b) { ... }  //< void fn(String,String)
var f = new Function('a', 'b', '...') //< void fn(String, Date)
</source>

|-
| style="border:1px solid #AAAAAA;padding: 0.2em;" | Statements 
| style="border:1px solid #AAAAAA;padding: 0.2em;" |<source lang="javascript">
// 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) {
}
</source>

|}


== 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">
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' ;
</source>

|-
| style="border:1px solid #AAAAAA;padding: 0.2em;" | Type of Array
| style="border:1px solid #AAAAAA;padding: 0.2em;" | <source lang="javascript">
var scores = [91, 77, 84] ; //< Number[]
var names = ['Mark', 'Sean', 'Juan'] ; //< String[]
names[3] = 'Justin' ;
scores[3] = 12 ;
</source>

|-
| style="border:1px solid #AAAAAA;padding: 0.2em;" | Two Dimensional Array
| style="border:1px solid #AAAAAA;padding: 0.2em;" | <source lang="javascript">
var keys = [ //< Number[][]
  [1, 2, 3],
  [4, 5, 6],
  [7, 8, 9]
];
</source>

|}


== Multi-Type Declarations ==

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 

|-
| 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}
</source>

|-
| style="border:1px solid #AAAAAA;padding: 0.2em;" | Function argument multi-type
| style="border:1px solid #AAAAAA;padding: 0.2em;" | <source lang="javascript">
//> void foo({int  String})
foo : function(x) {
}
</source>

|}

== Function Declarations ==


=== 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 
</source>
| style="border:1px solid #AAAAAA;padding: 0.2em;" | ''final'' is optional, but if used, appears before the return type 

|}

=== 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">
foo : function() { //< void
}
</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">
foo : function(x) { //< void foo(int x)
}
</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">
foo : function(x, y) { //< void foo(Number x, Function y)
}
</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">
//> void f({int  String})
foo : function(x){
}
</source>
| style="border:1px solid #AAAAAA;padding: 0.2em;" | VJETDoc supports the notion of a single argument having more than one valid type.&nbsp; 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">
foo : function(x) { //< void foo(int? x)
}

//> void foo(int x, int? y)foo : function(x, y) {
}
</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">
foo : function(args) { //< void foo(String... args) {
}

//> void foo(int x, String... args)foo : function(x, args) {
}
</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">
//> void dateProvider( (void f(Date)) needsAdate)
function dateProvider(needsAdate) {
  needsAdate(new Date) ;
}
</source>
| style="border:1px solid #AAAAAA;padding: 0.2em;" |  

|}

=== 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">
//> void f()
//> void f(int)
//> void f(String)
foo : f()
</source>

|-
| style="border:1px solid #AAAAAA;padding: 0.2em;" | Overload with vararg
| style="border:1px solid #AAAAAA;padding: 0.2em;" | <source lang="javascript">
//> void g(int?, String?)
function g() { }
</source>

|-
| style="border:1px solid #AAAAAA;padding: 0.2em;" |  Overload with different return types
| style="border:1px solid #AAAAAA;padding: 0.2em;" | <source lang="javascript">
//> Number add(Number, Number)
//> String add(String, String)
function add(a, b){
   return a + b ; }
</source>

 |}

=== Function Assignment ===

<source lang="javascript">
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
</source>


=== Calling a Function with Another Function as an Argument ===

<source lang="javascript">
//> 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() ; ')
);
</source>

=== A Function Returning a Function ===

We can type the return type of a function with VJETDoc

<source lang="javascript">
/*> (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)
</source>

=== 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.

<source lang="javascript">
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
</source>


== 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.

{| 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 ==

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">
var x ; //< X
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">
var d = something() ;
//<< Date ; this doubles as declaration and cast of something()
</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. 

|}


[[Category:VJET]]
[[Category:VJETDoc]]
[[Category:JavaScript]]