View source for VJET/Type Declarations Using 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.

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.&nbsp; With VJETDoc, JavaScript developers can precisely type their own API as well as understand those from others.



== VJETDoc Example ==

The following example illustrates the benefits of using VJETDoc to add type information to JavaScript.&nbsp; Once VJETDoc is added, the VJET JS IDE can validate code based on the type information.&nbsp; Developers can easily fix the errors using code assistance and proposals, again, based on the type information.
<br/>

The following JavaScript example has a number of errors, but the errors are difficult to detect.

<br/>
[[Image:Vjet_vjetDoc_errors_not_displayed.gif]]


=== Add VJETDoc to Validate JavaScript ===

Simply add VJETDoc to the function definition and VJET JS IDE has the information needed to validate the code.&nbsp; Note that VJET JS IDE validates implementation as well as invocation code.


<br/>
[[Image:Vjet_vjetDoc_add_vjet_comment.gif]]
<br/>

=== Get Error Details ===

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


===== Invalid Arguments =====
[[Image:Vjet_vjetDoc_invalid_args2.gif]]
<br/>

===== Undefined Function =====
[[Image:Vjet_vjetDoc_undefined.gif]]
<br/>

===== Wrong Return Type =====
[[Image:Vjet_vjetDoc_wrong_return.gif]]
<br/>

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

[[Image:Vjet_vjet_fix_invalid.gif]]

[[Image:Vjet_vjet_fix_undefined4.gif]]

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



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


The directional indicator allows you to position the VJETDoc statement before or after its intended source.&nbsp; 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,



<source lang="javascript">
var dd = new Date(); //<Date
</source>
To annotate a type itself, other than instance of a type, use the '''type::''' qualifier:

<source lang="javascript">
var D = Date;  //<type::Date
</source>

Array type can be represented as a generic array or typed array:

<source lang="javascript">
//<Array    //<String[]   //<int[]
</source>

Variant type (multi-types) can be denoted using 
<source lang="javascript">
{t1
| t2
| t3}
</source>
for example,

<source lang="javascript">
//<{String
| String[]
| Node}
</source>

Function can be represented as:

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <TYPE> <FN_NAME>()&nbsp; &nbsp;&nbsp;&nbsp; or&nbsp;&nbsp;&nbsp;&nbsp; <TYPE> <FN_NAME> (<ARG> <nowiki>[[</nowiki>,<ARG<nowiki>]]</nowiki>*)

<ARG> can be expressed as follows with the arg name being optional,

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <TYPE> <nowiki>[[</nowiki><ARG_NAME><nowiki>]]</nowiki>

Optional arg is marked with ''''?'''',

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <TYPE> ? <nowiki>[[</nowiki><ARG_NAME><nowiki>]]</nowiki>

Varargs is marked with ''''...'''',

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <TYPE> ...&nbsp; <nowiki>[[</nowiki><ARG_NAME><nowiki>]]</nowiki>

A function can only have one varargs, which also has to be the last arg.&nbsp; 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
| Node}, {String
| Node}?)
 }
</source>

If a return type or arg type itself is another function declaration, that type has to be surrounded by parentheses, for example,

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
<source lang="javascript">
//>(void fn(Date)) fn(String, (int fn(boolean, Node)))
var bar = function(id, callback) {
}
</source>

If a function is overloaded with multiple APIs, multiple VJETDoc statements can be used:

<source lang="javascript">
//>Object attr({Node
| String}, String name)
//>void attr({Node
| String}, String name, Object value)
//>void attr({Node
| String}, ObjLiteral nv)
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.&nbsp; For a quick overview refer to the [[VJET:VJETDoc Quick Reference]].

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