document haxe.macro.Type.hx (closes #4156) [skip ci]

std/haxe/macro/Type.hx

@@ -25,11 +25,22 @@ package haxe.macro;
     Warning: Some of these types correspond to compiler-internal data structures
     and might change in minor Haxe releases in order to adapt to internal changes.
 */
+
+/**
+	Represents a reference to internal compiler structure. It exists to avoid
+	expensive encoding if it is not required and to ensure that physical
+	equality remains intact.
+
+	A structure is only encoded when user requests it through `ref.get()`.
+*/
 typedef Ref<T> = {
 	public function get() : T;
 	public function toString() : String;
 }
 
+/**
+	Represents a type
+*/
 enum Type {
 	/**
 		Represents a monomorph.
@@ -93,103 +104,406 @@ enum Type {
 	TAbstract( t : Ref<AbstractType>, params : Array<Type> );
 }
 
+/**
+	Represents information for anonymous structure types.
+*/
 typedef AnonType = {
+	/**
+		The class fields of the structure.
+	**/
 	var fields : Array<ClassField>;
+	/**
+		The status/kind of the structure.
+	**/
 	var status : AnonStatus;
 }
 
+/**
+	Represents the kind of the anonymous structure type.
+**/
 enum AnonStatus {
+	/**
+		A closed structure is considered complete. That is, no further fields
+		can be added to it.
+	**/
 	AClosed;
+
+	/**
+		An open structure allows having additional fields added to it, which is
+		used during type inference. It is closed upon unification.
+	**/
 	AOpened;
+
+	/**
+		A const structure is one that appears directly in syntax. It cannot be
+		assigned to a smaller structure type (that is, it does not allow
+		structural sub-typing).
+	**/
 	AConst;
+
+	/**
+		Represents a structure which extends one or multiple structures defined
+		in `tl`.
+
+		@see http://haxe.org/manual/type-system-extensions.html
+	**/
 	AExtend( tl:Ref<Array<Type>> );
+
+	/**
+		A structure that represents the static fields of a class.
+	**/
 	AClassStatics( t : Ref<ClassType> );
+
+	/**
+		A structure that represents the constructors of an enum.
+	**/
 	AEnumStatics( t : Ref<EnumType> );
+
+	/**
+		A structure that represents the static fields of an abstract.
+	**/
 	AAbstractStatics( t : Ref<AbstractType> );
 }
 
+/**
+	Represents the declaration of type parameters.
+*/
 typedef TypeParameter = {
+	/**
+		The name of the type parameter
+	**/
 	var name: String;
-	var t: Type;
-}
 
-typedef BaseType = {
-	var pack : Array<String>;
-	var name : String;
-	var module : String;
-	var pos : Expr.Position;
-	var isPrivate : Bool;
-	var isExtern : Bool;
-	var params : Array<TypeParameter>;
-	var meta : MetaAccess;
-	var doc : Null<String>;
-	function exclude() : Void;
+	/**
+		The type of the type parameter. It is guaranteed to be a `TInst` with a
+		`KTypeParameter` kind.
+	**/
+	var t: Type;
 }
 
+/**
+	Represents a class field.
+*/
 typedef ClassField = {
+	/**
+		The name of the class field
+	**/
 	var name : String;
+
+	/**
+		The type of the class field
+	**/
 	var type : Type;
+
+	/**
+		Whether or not the class field is public
+	**/
 	var isPublic : Bool;
+
+	/**
+		The type parameters of the class field
+	**/
 	var params : Array<TypeParameter>;
+
+	/**
+		The metadata of the class field
+	**/
 	var meta : MetaAccess;
+
+	/**
+		The class field kind
+	**/
 	var kind : FieldKind;
+
+	/**
+		Returns the typed expression of the class field.
+	**/
 	function expr() : Null<TypedExpr>;
+
+	/**
+		The position of the class field
+	**/
+	var pos : Expr.Position;
+
+	/**
+		The associated documentation of the class field
+	**/
+	var doc : Null<String>;
+}
+
+/**
+	Represents an enum constructor
+*/
+typedef EnumField = {
+	/**
+		The name of the enum constructor
+	**/
+	var name : String;
+
+	/**
+		The type of the enum constructor
+	**/
+	var type : Type;
+
+	/**
+		The position of the enum constructor
+	**/
 	var pos : Expr.Position;
+
+	/**
+		The metadata of the enum constructor
+	**/
+	var meta : MetaAccess;
+
+	/**
+		The index of the enum constructor, i.e. in which position it appears
+		in the syntax
+	**/
+	var index : Int;
+
+	/**
+		The associated documentation of the enum constructor
+	**/
 	var doc : Null<String>;
+
+	/**
+		The type parameters of the enum constructor
+	**/
+	var params : Array<TypeParameter>;
 }
 
+
+/**
+	Represents the kind of a class.
+*/
 enum ClassKind {
+	/**
+		A normal class
+	**/
 	KNormal;
+
+	/**
+		A type parameter class with a set of constraints
+	**/
 	KTypeParameter(constraints:Array<Type>);
+
+	/**
+		A structurally extended class
+
+		@deprecated
+	**/
 	KExtension(cl:Ref<ClassType>, params:Array<Type>);
+
+	/**
+		A special kind of class to encode expressions into type parameters
+	**/
 	KExpr(expr:Expr);
+
+	/**
+		A `@:generic` base class
+	**/
 	KGeneric;
+
+	/**
+		A concrete `@:generic` instance, referencing the original class and the
+		applied type parameters
+	**/
 	KGenericInstance(cl:Ref<ClassType>, params:Array<Type>);
+
+	/**
+		A special class for `haxe.macro.MacroType`
+
+		@deprecated
+	**/
 	KMacroType;
+
+	/**
+		An implementation class of an abstract, i.e. where all its run-time code
+		is
+	**/
 	KAbstractImpl(a:Ref<AbstractType>);
+
+	/**
+		A `@:genericBuild` class
+	**/
 	KGenericBuild;
 }
 
+/**
+	The information that all types (`ClassType`, `EnumType`, `DefType`,
+	`AbstractType`) have in common
+**/
+typedef BaseType = {
+	/**
+		The package of the type
+	**/
+	var pack : Array<String>;
+
+	/**
+		The name of the type
+	**/
+	var name : String;
+
+	/**
+		The module name of the type, which might be different
+	**/
+	var module : String;
+
+	/**
+		The position of the type
+	**/
+	var pos : Expr.Position;
+
+	/**
+		Whether or not the type is private
+	**/
+	var isPrivate : Bool;
+
+	/**
+		Whether or not the type is extern
+	**/
+	var isExtern : Bool;
+
+	/**
+		The type parameters of the type
+	**/
+	var params : Array<TypeParameter>;
+
+	/**
+		The metadata of the type
+	**/
+	var meta : MetaAccess;
+
+	/**
+		The associated documentation of the class field
+	**/
+	var doc : Null<String>;
+
+	/**
+		Allows excluding the type from compilation
+	**/
+	function exclude() : Void;
+}
+
+/**
+	Represents a class type
+*/
 typedef ClassType = {> BaseType,
+	/**
+		The kind of the class
+	**/
 	var kind : ClassKind;
+
+	/**
+		If true the type is an interface, otherwise it is a class
+	**/
 	var isInterface : Bool;
+
+	/**
+		The parent class and its type parameters, if available
+	**/
 	var superClass : Null<{ t : Ref<ClassType>, params : Array<Type> }>;
+
+	/**
+		The implemented interfaces and their type parameters
+	**/
 	var interfaces : Array<{ t : Ref<ClassType>, params : Array<Type> }>;
+
+	/**
+		The member fields of the class
+	**/
 	var fields : Ref<Array<ClassField>>;
+
+	/**
+		The static fields of the class
+	**/
 	var statics : Ref<Array<ClassField>>;
+
 	//var dynamic : Null<Type>;
 	//var arrayAccess : Null<Type>;
+
+	/**
+		The constructor of the class, if available
+	**/
 	var constructor : Null<Ref<ClassField>>;
+
+	/**
+		The `__init__` expression of the class, if available
+	**/
 	var init : Null<TypedExpr>;
-	var overrides : Array<Ref<ClassField>>;
-}
 
-typedef EnumField = {
-	var name : String;
-	var type : Type;
-	var pos : Expr.Position;
-	var meta : MetaAccess;
-	var index : Int;
-	var doc : Null<String>;
-	var params : Array<TypeParameter>;
+	/**
+		The list of fields that have override status
+	**/
+	var overrides : Array<Ref<ClassField>>;
 }
 
+/**
+	Represents an enum type
+*/
 typedef EnumType = {> BaseType,
-	var constructs : Map<String,EnumField>;
+	/**
+		The available enum constructors
+	**/
+	var constructs : Map<String, EnumField>;
+
+	/**
+		An ordered list of enum constructor names
+	**/
 	var names : Array<String>;
 }
 
+/**
+	Represents a typedef
+*/
 typedef DefType = {> BaseType,
+	/**
+		The target type of the typedef
+	**/
 	var type : Type;
 }
 
+/**
+	Represents an abstract type
+*/
 typedef AbstractType = {>BaseType,
+	/**
+		The underlying type of the abstract
+	**/
 	var type : Type;
+
+	/**
+		The implementation class of the abstract, if available
+	**/
 	var impl : Null<Ref<ClassType>>;
+
+	/**
+		The defined binary operators of the abstract
+	**/
 	var binops : Array<{op:Expr.Binop, field:ClassField}>;
+
+	/**
+		The defined unary operators of the abstract
+	**/
 	var unops : Array<{op:Expr.Unop, postFix:Bool, field:ClassField}>;
+
+	/**
+		The available implicit from-casts of the abstract
+
+		@see http://haxe.org/manual/types-abstract-implicit-casts.html
+	**/
 	var from : Array<{t:Type, field:Null<ClassField>}>;
+
+	/**
+		The available implicit to-casts of the abstract
+
+		@see http://haxe.org/manual/types-abstract-implicit-casts.html
+	**/
 	var to : Array<{t:Type, field:Null<ClassField>}>;
+
+	/**
+		The defined array-access fields of the abstract
+	**/
 	var array : Array<ClassField>;
 }
 
@@ -250,100 +564,413 @@ typedef MetaAccess = {
 	function has( name : String ) : Bool;
 }
 
+/**
+	Represents a field kind
+*/
 enum FieldKind {
+	/**
+		A variable of property, depending on the `read` and `write` values
+	**/
 	FVar( read : VarAccess, write : VarAccess );
+
+	/**
+		A method
+	**/
 	FMethod( k : MethodKind );
 }
 
+/**
+	Represents the variable accessor
+*/
 enum VarAccess {
+	/**
+		Normal access (`default`)
+	**/
 	AccNormal;
+
+	/**
+		Private access (`null`)
+	**/
 	AccNo;
+
+	/**
+		No access (`never`)
+	**/
 	AccNever;
+
+	/**
+		Unused
+	**/
 	AccResolve;
+
+	/**
+		Access through accessor function (`get`, `set`, `dynamic`)
+	**/
 	AccCall;
+
+	/**
+		Inline access (`inline`)
+	**/
 	AccInline;
+
+	/**
+		Failed access due to a `@:require` metadata
+	**/
 	AccRequire( r : String, ?msg : String );
 }
 
+/**
+	Represents the method kind
+*/
 enum MethodKind {
+	/**
+		A normal method
+	**/
 	MethNormal;
+
+	/**
+		An inline method
+
+		@see http://haxe.org/manual/class-field-inline.html
+	**/
 	MethInline;
+
+	/**
+		A dynamic, rebindable method
+
+		@see http://haxe.org/manual/class-field-dynamic.html
+	**/
 	MethDynamic;
+
+	/**
+		A macro method
+	**/
 	MethMacro;
 }
 
+/**
+	Represents typed constant
+*/
 enum TConstant {
+	/**
+		An `Int` literal
+	**/
 	TInt(i:Int);
+
+	/**
+		A `Float` literal, represented as String to avoid precision loss
+	**/
 	TFloat(s:String);
+
+	/**
+		A `String` literal
+	**/
 	TString(s:String);
+
+	/**
+		A `Bool` literal
+	**/
 	TBool(b:Bool);
+
+	/**
+		The constant `null`
+	**/
 	TNull;
+
+	/**
+		The constant `this`
+	**/
 	TThis;
+
+	/**
+		The constant `super`
+	**/
 	TSuper;
 }
 
+/**
+	Represents a variable in the typed AST.
+*/
 typedef TVar = {
+	/**
+		The unique ID of the variable
+	**/
 	public var id(default, never):Int;
+
+	/**
+		The name of the variable
+	**/
 	public var name(default, never):String;
+
+	/**
+		The type of the variable
+	**/
 	public var t(default, never):Type;
+
+	/**
+		Whether or not the variable has been captured by a closure
+	**/
 	public var capture(default, never):Bool;
+
+	/**
+		Special information which is internally used to keep track of closure
+		information
+	**/
 	public var extra(default,never):Null<{params: Array<TypeParameter>, expr: Null<TypedExpr>}>;
 }
 
+/**
+	Represents a module type. These are the types that can be declared in a Haxe
+	module and which are passed to the generators (except `TTypeDecl`).
+*/
 enum ModuleType {
+	/**
+		A class
+	**/
 	TClassDecl(c:Ref<ClassType>);
+
+	/**
+		An enum
+	**/
 	TEnumDecl(e:Ref<EnumType>);
+
+	/**
+		A typedef
+	**/
 	TTypeDecl(t:Ref<DefType>);
+
+	/**
+		An abstract
+	**/
 	TAbstract(a:Ref<AbstractType>);
 }
 
+/**
+	Represents a function in the typed AST.
+*/
 typedef TFunc = {
-	args: Array<{v:TVar, value:Null<TConstant>}>,
-	t: Type,
-	expr: TypedExpr
+	/**
+		A list of function arguments identified by an argument variable `v` and
+		an optional initialization `value`.
+	**/
+	var args: Array<{v:TVar, value:Null<TConstant>}>;
+
+	/**
+		The return type of the function
+	**/
+	var t: Type;
+
+	/**
+		The expression of the function body
+	**/
+	var expr: TypedExpr;
 }
 
+/**
+	Represents the kind of field access in the typed AST.
+*/
 enum FieldAccess {
+	/**
+		Access of field `cf` on a class instance `c` with type parameters
+		`params`
+	**/
 	FInstance(c:Ref<ClassType>, params:Array<Type>, cf:Ref<ClassField>);
+
+	/**
+		Static access of a field `cf` on a class `c`
+	**/
 	FStatic(c:Ref<ClassType>, cf:Ref<ClassField>);
+
+	/**
+		Access of field `cf` on an anonymous structure
+	**/
 	FAnon(cf:Ref<ClassField>);
+
+	/**
+		Dynamic field access of a field named `s`
+	**/
 	FDynamic(s:String);
+
+	/**
+		Closure field access of field `cf` on a class instance `c` with type
+		parameters `params`
+	**/
 	FClosure(c:Null<{c:Ref<ClassType>, params:Array<Type>}>, cf:Ref<ClassField>);
+
+	/**
+		Field access to an enum constructor `ef` of enum `e`
+	**/
 	FEnum(e:Ref<EnumType>, ef:EnumField);
 }
 
+/**
+	Represents kind of a node in the typed AST
+*/
 enum TypedExprDef {
+	/**
+		A constant
+	**/
 	TConst(c:TConstant);
+
+	/**
+		Reference to a local variable `v`
+	**/
 	TLocal(v:TVar);
+
+	/**
+		Array access `e1[e2]`
+	**/
 	TArray(e1:TypedExpr, e2:TypedExpr);
+
+	/**
+		Binary operator `e1 op e2`
+	**/
+
 	TBinop(op:Expr.Binop, e1:TypedExpr, e2:TypedExpr);
+
+	/**
+		Field access on `e` according to `fa`
+	**/
 	TField(e:TypedExpr, fa:FieldAccess);
+
+	/**
+		Reference to a module type `m`
+	**/
 	TTypeExpr(m:ModuleType);
+
+	/**
+		Parentheses `(e)`
+	**/
 	TParenthesis(e:TypedExpr);
+
+	/**
+		An object declaration
+	**/
 	TObjectDecl(fields:Array<{name:String, expr:TypedExpr}>);
+
+	/**
+		An array declaration `[el]`
+	**/
 	TArrayDecl(el:Array<TypedExpr>);
+
+	/**
+		A call `e(el)`
+	**/
 	TCall(e:TypedExpr, el:Array<TypedExpr>);
+
+	/**
+		A constructor call `new c<params>(el)`
+	**/
 	TNew(c:Ref<ClassType>, params: Array<Type>, el:Array<TypedExpr>);
+
+	/**
+		An unary operator `op` on `e`:
+
+		* e++ (op = OpIncrement, postFix = true)
+		* e-- (op = OpDecrement, postFix = true)
+		* ++e (op = OpIncrement, postFix = false)
+		* --e (op = OpDecrement, postFix = false)
+		* -e (op = OpNeg, postFix = false)
+		* !e (op = OpNot, postFix = false)
+		* ~e (op = OpNegBits, postFix = false)
+	**/
 	TUnop(op:Expr.Unop, postFix:Bool, e:TypedExpr);
+
+	/**
+		A function declaration
+	**/
 	TFunction(tfunc:TFunc);
+
+	/**
+		A variable declaration `var v` or `var v = expr`
+	**/
 	TVar(v:TVar, expr:Null<TypedExpr>);
+
+	/**
+		A block declaration `{el}`.
+	**/
 	TBlock(el:Array<TypedExpr>);
+
+	/**
+		A `for` expression
+	**/
 	TFor(v:TVar, e1:TypedExpr, e2:TypedExpr);
+
+	/**
+		An `if(econd) eif` or `if(econd) eif else eelse` expression
+	**/
 	TIf(econd:TypedExpr, eif:TypedExpr, eelse:Null<TypedExpr>);
+
+	/**
+		Represents a `while` expression.
+		When `normalWhile` is `true` it is `while (...)`
+		When `normalWhile` is `false` it is `do {...} while (...)`
+	**/
 	TWhile(econd:TypedExpr, e:TypedExpr, normalWhile:Bool);
+
+	/**
+		Represents a `switch` expression with related cases and an optional
+		`default` case if edef != null.
+	**/
 	TSwitch(e:TypedExpr, cases:Array<{values:Array<TypedExpr>, expr:TypedExpr}>, edef:Null<TypedExpr>);
+
+	/**
+		Represents a `try`-expression with related catches.
+	**/
 	TTry(e:TypedExpr, catches:Array<{v:TVar, expr:TypedExpr}>);
+
+	/**
+		A `return` or `return e` expression
+	**/
 	TReturn(e:Null<TypedExpr>);
+
+	/**
+		A `break` expression
+	**/
 	TBreak;
+
+	/**
+		A `continue` expression
+	**/
 	TContinue;
+
+	/**
+		A `throw e` expression
+	**/
 	TThrow(e:TypedExpr);
+
+	/**
+		A `cast e` or `cast (e, m)` expression
+	**/
 	TCast(e:TypedExpr, m:Null<ModuleType>);
+
+	/**
+		A `@m e1` expression
+	**/
 	TMeta(m:Expr.MetadataEntry, e1:TypedExpr);
+
+	/**
+		Access to an enum parameter (generated by the pattern matcher)
+	**/
 	TEnumParameter(e1:TypedExpr, ef:EnumField, index:Int);
 }
 
+/**
+	Represents a typed AST node
+*/
 typedef TypedExpr = {
-	expr: TypedExprDef,
-	pos: Expr.Position,
-	t: Type
+	/**
+		The expression kind
+	**/
+	var expr: TypedExprDef;
+
+	/**
+		The position of the expression
+	**/
+	var pos: Expr.Position;
+
+	/**
+		The type of the expression
+	**/
+	var t: Type;
 }