Difference between revisions of "VJET/Type Declarations Using VJETDoc"

Revision as of 22:24, 28 November 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.

{toc}

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.

!vjetDoc_errors_not_displayed.gif | border=1!

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.

!vjetDoc_add_vjet_comment.gif | border=1!

Get Error Details

Hover over the error markers or the underlined text to view error details.

Invalid Arguments

!vjetDoc_invalid_args2.gif | border=1!

Undefined Function

!vjetDoc_undefined.gif | border=1!

Wrong Return Type

!vjetDoc_wrong_return.gif | border=1!

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. !vjet_fix_invalid.gif | border=1! !vjet_fix_undefined4.gif | border=1!

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.