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 Syntax
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
Contents
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> >