Latest revision as of 13:58, 5 December 2012

VJET defines the following terms so that we can describe the various portions of VJETDoc.  We also combine these terms to create higher-level terms and constructs.  Collectively these terms and constructs describe all the parts of a VJETDoc.

A Vjet type can convey a lot of information:

• Access Control (public, protected, private)
  
• Refinement Qualifier (abstract, final)
  
• What type
  
• Array (single or multi-dimension)
  
• Generics ( <T> , <T extends OtherType>, wildcards etc...)
  
• Functions (return type, arguments, throws clause)
  

Comment structure

Vjet-start someTypeInfo [; other comment text]  [Vjet-end]Vjet-start: //< 
|  //> 
|  /*< 
|  /*> 
|  /**> 
|  /**<
Vjet-end: {empty} 
|  */

We can describe comments as comment start/end and factor out the comment body.  The body can be vjet declaration-info followed by [; any other comment text].

The vast diversity of the comment is in the declaration-info .

If we break declaration-info into pieces we generally have: Qualifier-Info  Type-Info

Qualifier-Info: [access-control] [refinement-qualifier]

Type-info:  TypeName | Type-Reference | Function-info

Type-Name is name or dot name

Type-Reference is type:: Type-Name

Type-info comes in a number of flavors.  Probably the major breakdown is between identifying a type itself (a type name, a type reference,

The type name itself is pretty simple:  int, String, a.b.Xyz.

Suffix-Info: [generic] [array]

Depending on what the VJETDoc needs to describe can impact which parts of the SomeTypeInfo are valid.  For example on a Vjet type itself we only have Suffix-Info but not Type or Prefix-Info.  And, we only allow a subset of Suffix-Info.  This is why doing BNF style is a bit messy.  Perhaps we can just have a minimal set and compose from that set for each of the places we can apply the VJETDoc?

When we think about a Vjet type itself, we have access-control and type-qualifiers.  Different vjo types have differing values.  For example an etype cannot be abstract.  In these cases we don't need to redefine what a VJETDoc is, we only need to say what access-control and type-qualifiers are valid.

We need to think of free-form JavaScript as well as structured Vjet JavaScript.  Probably the only case where this really matters is in the case of globals.  Vjet has a formal way to define a global as well as a non-var in any function is another way to be a global.  Vjet typing can flag a non-var usage as an error. 

We have global variables and local variables

We have function arguments

We have member function declarations

We have member non-function declarations

We have floating functions

We have object literals.  In otype scenarios we only have to type the name:value relationship.  The say goes for free-form object literals as well.  However, in an otype, we can apply the access-control to the namespace on which the OL is defined under.

In an otype, we allow a formal typing of a function itself.  This is not different from typing a floating function.  We do have the special case where a floating function is assigned to a variable and we type both with a single declaration.

We have to describe what type we want to type with.  This can include a reference to a type

We also have functions that appear in a number of places.  We also have the added complexity of having to be able to describe a function that can be passed as an argument or returned from another function

Basic Terms and Structure

There are a many places we can use VJETDoc to declare our JavaScript code. 

Qualifiers

Access-Control:  public   |   protected   |   private

Refinement-Qualifier:  abstract | final

Type-Qualifier:  [Access-Control]  [Refinement-Qualifier]

 Type Decl

Type-Decl:  Type-Name  |  Type-Reference  |   Function-Declaration   |   Function-Declaration-Ref

Type Extensions

We group arrays and generics into type extensions.  The reason for this is that nearly every type we describe we can :

• have an array of them
• have a parameterized declaration of it
• a parameterized declaration can include an array declaration

Generics (Parameterized Types)

Only Vjet types (not native JavaScript types) can be parameterized.

List<int>,  Map<String, work.Timer>, Set< List<String> >