Index of annotations

GAMA extensions describe their GAML elements (operators, statements, skills, species, types, files...) with Java annotations. All the annotations are in the package gama.annotations of the plugin gama.annotations (gama.annotations/src/gama/annotations/). The annotation processor gama.processor reads them when the plugin is compiled. It:

• checks them and reports errors and warnings in the Eclipse Problems view;
• generates the class gaml.additions.<shortcut>.GamlAdditions in the gaml/ folder of the plugin, which registers the elements in GAMA when the plugin is loaded. Never edit the gaml/ folder by hand;
• generates GAML test models from @test and @example (and fuzz tests for operators) in gaml/models/Tests/Generated From <Plugin>/models/;
• collects the documentation used to build the GAML reference.

For the set-up of a plugin, see Developing Plugins. For tutorials, see Developing Operators, Developing Statements, Developing Skills, Developing Species, Developing Types and Developing Control Architectures.

In the tables below, "(required)" means that the attribute has no default value. "Type id" means an int that is either an IType constant (IType.INT, IType.LIST...) or, where it makes sense, an ITypeProvider constant. "Doc" means the documentation of the element, written with @doc.

Summary

Annotation	Placed on	Declares
@action	method	an action of a skill, species or class
@arg	inside @action	an argument of an action
@constant	static field	a constant (#name)
@display	class	a type of display
@doc	class, method, or inside other annotations	documentation
@example	inside @doc and @usage	an example (and a test)
@experiment	class	a type of experiment
@facet	inside @facets	a facet of a statement
@facets	class	the facets of a statement
@file	class	a type of file
@gaml_class	class	a GAML class (non-agent objects)
@getter	method	the getter of an attribute
@inside	class	where a statement can be used
@listener	method	a method called when an attribute changes
@no_fuzz_test	method, class	excludes an operator from fuzz tests
@no_test	method	marks an operator as not needing a test
@operator	method	an operator
@setter	method	the setter of an attribute
@skill	class	a skill, or a control architecture
@species	class	a built-in species
@symbol	class	a statement (or another symbol)
@test / @tests	method, class	GAML tests
@type	class	a data type
@usage	inside @doc	a particular usage of an element
@variable	inside @vars	an attribute
@vars	class, interface	the attributes of a skill, species, class or value

Three more annotations are defined in gama.api (package gama.api.annotations): @validator, @serializer and @depends_on.

---

@action

@Target(METHOD). Defines an action of a skill, an architecture, a species (agent class) or a GAML class. The method must take an IScope as its only parameter. It reads the arguments from the scope (e.g. scope.getArg("other", IType.AGENT)), and its Java return type gives the return type of the action (void for actions that return nothing). See Developing Skills.

Attribute	Type	Default	Meaning
name	String	(required)	The name of the action in GAML.
args	arg[]	{}	The arguments of the action (see @arg).
virtual	boolean	false	true if the action is abstract: it must be redefined in the GAML species that use it (e.g. related_to of graph_node).
internal	boolean	false	true to hide the action from the documentation and the completion.
doc	doc[]	{}	Doc.

The processor reports an error if two arguments have the same name, and a warning if an argument is named name, keyword or returns (such an action cannot be called with facets, like do action arg1: val1).

@arg

Used inside @action(args = {...}). Describes an argument of an action.

Attribute	Type	Default	Meaning
name	String	""	The name of the argument.
type	int	0	Type id of the argument.
optional	boolean	true	false if the argument is mandatory.
doc	doc[]	{}	Doc.

@constant

@Target(FIELD). Defines a constant or a unit, used in GAML with # (e.g. #pi, #km). It is placed on a static field, whose value is the value of the constant. Constants are not registered by GamlAdditions: a class implementing gama.api.additions.delegates.IConstantsSupplier, contributed through the extension point gama.constants, browses the annotated fields. See gama.extension.maths/src/gama/extension/maths/ode/MathConstants.java and MathConstantSupplier.java:

@constant (
        value = "rk4",
        category = { IConstantCategory.MATH },
        concept = { IConcept.EQUATION, IConcept.CONSTANT },
        doc = @doc ("rk4 solver")) String rk4 = "rk4";

Attribute	Type	Default	Meaning
value	String	(required)	The name of the constant (without #). It does not need to be unique.
altNames	String[]	{}	Other names of the constant.
category	String[]	{}	Categories of the documentation. Use the constants of IConstantCategory.
concept	String[]	{}	Concepts, from IConcept.
doc	doc[]	{}	Doc.

@display

@Target(TYPE), inherited. Defines a type of display (the value of type: in display my_display type: ...). The class must implement gama.api.ui.displays.IDisplaySurface and have a constructor (IOutput.Display output, Object uiComponent). Examples: Java2DDisplaySurface (java2d, 2d) in gama.ui.display.java2d, SWTOpenGLDisplaySurface (opengl) in gama.ui.display.opengl.

Attribute	Type	Default	Meaning
value	String[]	(required)	The keyword(s) of the display type.
viewId	String	""	The id of the Eclipse view that hosts the display surface.
is3D	boolean	false	true if the display is a 3D display.

@doc

@Target({TYPE, METHOD}), and used in the doc attribute of most annotations. Documents a GAML element. The documentation of GAML is generated from it, and the processor reports a warning ("documentation missing") for each element without it.

Attribute	Type	Default	Meaning
value	String	""	The main description.
returns	String	""	What the element returns (operators, actions).
comment	String	""	An additional comment.
special_cases	String[]	{}	Special cases (e.g. what happens with nil or negative values).
examples	example[]	{}	Examples (see @example). Examples can become tests.
usages	usage[]	{}	Particular usages of the element (see @usage).
see	String[]	{}	Names of related elements.
side_effects	String	""	Side effects of the element.
deprecated	String	""	If not empty, the element is deprecated, and the text explains what to use instead.
masterDoc	boolean	false	When several Java elements share the same GAML name (overloaded operators, actions defined in several skills...), marks the documentation to use as the main one.

@example

Can only be used inside @doc(examples = ...) and @usage(examples = ...). An example is a line of GAML code. If it has equals, isNot or raises, it is also turned into a test.

Attribute	Type	Default	Meaning
value	String	""	The GAML code of the example.
equals	String	""	The expected result. Generates a test checking value = equals.
isNot	String	""	A value that the result must be different from.
raises	String	""	The error or warning that the code is expected to raise.
var	String	""	The name of the variable that holds the result in the generated test.
returnType	String	""	The type of the result (used in the generated test).
isExecutable	boolean	true	false if the code cannot be run alone (e.g. it uses variables defined elsewhere).
test	boolean	true	false to show the result in the documentation without testing it.
isTestOnly	boolean	false	true if the example is only a test, and must not appear in the documentation.
isPattern	boolean	false	true if the code is a pattern with placeholders such as ${action_name}.

@experiment

@Target(TYPE), inherited. Defines a type of experiment (the value of type: in experiment my_exp type: ...). The class must implement gama.api.kernel.simulation.IExperimentAgent (usually by extending gama.core.experiment.ExperimentAgent) and have a constructor (IPopulation<? extends IAgent>, int). Examples: ExperimentAgent (gui), TestAgent (test) in gama.core, BatchAgent (batch) in gama.extension.batch.

Attribute	Type	Default	Meaning
value	String	(required)	The keyword identifying the experiment type in GAML.

@facet

Used inside @facets(value = {...}). Describes a facet of a statement. See Developing Statements.

Attribute	Type	Default	Meaning
name	String	(required)	The name of the facet. It must be unique in the statement.
type	int[]	(required)	Accepted expression type IDs (several allowed), or exactly one variable type descriptor when declares_new_temp = true. IType.ID denotes an identifier; IType.NEW_VAR_ID remains available for non-temporary variable declarations.
declares_new_temp	boolean	false	Declares a new temporary identifier instead of accepting an expression. Its variable type is described independently by type, of, and index. Replaces the removed IType.NEW_TEMP_ID.
of	int	0	The container content type ID. On a temporary-declaring facet, also accepts STATEMENT_TYPE or INFERRED_TYPE. Does not imply a container outer type.
index	int	0	The container key type ID. On a temporary-declaring facet, also accepts STATEMENT_TYPE or INFERRED_TYPE.
values	String[]	{}	The list of accepted values, if the facet only accepts some keywords (e.g. values = {"line", "point"}).
optional	boolean	false	true if the facet can be omitted.
remote_context	boolean	false	true if the expression of the facet is evaluated in the context of the agents of the species denoted by the statement (self is then such an agent and myself is the caller), as in create ... with:.
internal	boolean	false	true to hide the facet from the documentation.
doc	doc[]	{}	Doc.

For example, @facet(name = IKeyword.RETURNS, declares_new_temp = true, type = IType.LIST, of = IType.FLOAT, optional = true) declares a list<float>, as used by benchmark. See Declaring temporary variables for contextual types, runtime scope handling, and migration from the old marker.

@facets

@Target(TYPE), inherited. Lists the facets of a statement (a class annotated with @symbol).

Attribute	Type	Default	Meaning
value	facet[]	(required)	The facets.
omissible	String	IKeyword.NAME ("name")	The facet whose name can be omitted: its value then directly follows the keyword (e.g. state s1 instead of state name: s1).

@file

@Target(TYPE), inherited. Defines a type of file. The class must implement gama.api.types.file.IGamaFile and have at least one constructor (IScope, String). The processor generates:

• the operator <name>_file, with one variant for each public constructor whose first parameter is an IScope (e.g. dxf_file(path) and dxf_file(path, unit));
• the operator is_<name>, which tests if a file is of this type.

Example: gama.extension.dxf/src/gama/extension/dxf/GamaDXFFile.java:

@file (
        name = "dxf",
        extensions = { "dxf" },
        buffer_type = IType.LIST,
        buffer_content = IType.GEOMETRY,
        buffer_index = IType.INT,
        concept = { "dxf", IConcept.FILE },
        doc = @doc ("DXF files are 2D geometrical files. The internal representation is a list of geometries"))

Attribute	Type	Default	Meaning
name	String	(required)	The name of the file type. It is used to build the names of the operators.
extensions	String[]	(required)	The file extensions recognized (without the dot).
buffer_type	int	ITypeProvider.NONE	Type id of the contents of the file once read (e.g. IType.LIST, IType.MATRIX).
buffer_content	int	ITypeProvider.NONE	Type id of the elements of the contents.
buffer_index	int	ITypeProvider.NONE	Type id of the index of the contents.
concept	String[]	{}	Concepts.
category	String[]	{}	Categories of the documentation.
doc	doc[]	{}	Doc.

@gaml_class

@Target(TYPE). Defines a built-in GAML class: a type of structured objects that are not agents (see Developing Species and the migration guide). The class must be public (top-level or static nested), implement gama.api.kernel.object.IObject (usually by extending gama.core.object.GamlObject), and have a public constructor (IScope, IClass). Agents cannot use this annotation (use @species). The GAML parent is the nearest Java superclass that is also annotated with @gaml_class, otherwise object. Example: gama.core/src/gama/core/util/CommandContext.java (class context).

Attribute	Type	Default	Meaning
name	String	(required)	The name of the class in GAML. It must not be empty.
concept	String[]	{}	Concepts.
doc	doc[]	{}	Doc.

@getter

@Target(METHOD). Marks the method that returns the value of an attribute declared with @variable.

Attribute	Type	Default	Meaning
value	String	(required)	The name of the attribute.
initializer	boolean	false	true if the getter also gives the initial value of the attribute (when no init is given).

The parameters of the method depend on the class that declares the attribute:

• in a skill or an architecture (one instance for all the agents): (IAgent agent), optionally preceded by an IScope;
• in an agent class, a GAML class or a value class: no parameter, or only an IScope.

@inside

@Target(TYPE), inherited. Placed on a statement (a class annotated with @symbol), it says where the statement can be used. The processor warns if a @symbol has no @inside.

Attribute	Type	Default	Meaning
symbols	String[]	{}	The keywords of the statements in which this statement can be used (e.g. IKeyword.DRAW). For behaviors of a control architecture, the name of the architecture (e.g. IKeyword.FSM).
kinds	ISymbolKind[]	{}	The kinds of statements in which this statement can be used (e.g. ISymbolKind.SPECIES, ISymbolKind.SEQUENCE_STATEMENT). See ISymbolKind.

@listener

@Target(METHOD). Marks a method that is called each time the value of an attribute changes. The attribute can be defined elsewhere, for example in another skill (e.g. @listener(IKeyword.LOCATION) in gama.extension.physics/src/gama/extension/physics/gaml/StaticBodySkill.java). If the attribute does not exist, the listener has no effect. The method receives the new value as last parameter, optionally preceded by an IScope and, in a skill, by the IAgent.

Attribute	Type	Default	Meaning
value	String	(required)	The name of the attribute to listen to.

@no_fuzz_test

@Target({METHOD, TYPE}), source retention. Fuzz tests call every operator at compile time with extreme values (0, -1, infinities, NaN, empty containers, nil) and check that they do not crash GAMA. This annotation excludes an operator (or all the operators of a class) from these tests: use it for operators that act on the outside world (files, network, user interface) or that can hang or use all the memory. Operators annotated with @no_test are not fuzz tested either.

Attribute	Type	Default	Meaning
value	String	(required)	The reason, e.g. "acts on the outside world (files, network, clipboard, user interface, shell...)".

@no_test

Source retention. Marks an operator that does not need a test: the warning "operator '...' is not tested" is not reported.

Attribute	Type	Default	Meaning
value	Reason	Reason.NONE	Why there is no test. See Reason.

@operator

@Target({METHOD, TYPE}). Defines an operator. See Developing Operators.

• With a static method, the operands are the parameters of the method.
• With an instance method, the object that declares the method is the first operand, and the parameters are the next operands.
• In both cases, if the first parameter is an IScope, it is given by GAMA and is not an operand.

The processor reports errors if the method is not public, returns void, uses Java arrays, or (static methods) has no operand.

Attribute	Type	Default	Meaning
value	String[]	(required)	The name(s) of the operator.
category	String[]	{}	Categories of the documentation, from IOperatorCategory.
concept	String[]	{}	Concepts, from IConcept.
can_be_const	boolean	false	true if the result only depends on the operands: if they are all constant, the operator is computed at compile time.
iterator	boolean	false	true if the operator is an iterator: its right operand is evaluated for each element of the left one, with the pseudo-variable each.
type	int	ITypeProvider.NONE	The return type (type id or ITypeProvider constant), when the Java return type is not precise enough (e.g. Object).
content_type	int	ITypeProvider.NONE	The content type of the result, if it is a container.
index_type	int	ITypeProvider.NONE	The index type of the result, if it is a container.
content_type_content_type	int	ITypeProvider.NONE	The content type of the contents of the result, for containers of containers.
expected_content_type	int[]	{}	The content types accepted for the operands (e.g. IType.BOOL for the filter of count).
internal	boolean	false	true to hide the operator from the documentation. Internal operators are not checked for tests.
doc	doc[]	{}	Doc (it is more usual to put @doc on the method).

@setter

@Target(METHOD). Marks the method that changes the value of an attribute declared with @variable. The method must have at least one parameter: the new value, as last parameter. It can be preceded by an IScope and, in a skill or an architecture, by the IAgent.

Attribute	Type	Default	Meaning
value	String	(required)	The name of the attribute.

@skill

@Target(TYPE). Defines a skill. The class must implement gama.api.kernel.skill.ISkill (usually by extending gama.api.kernel.skill.Skill). A class that also implements IArchitecture defines a control architecture (see Developing Control Architectures). See Developing Skills.

Attribute	Type	Default	Meaning
name	String	(required)	The name of the skill (or of the architecture).
attach_to	String[]	{}	Names of species to which the skill is attached automatically.
concept	String[]	{}	Concepts.
category	String[]	{}	Categories of the documentation.
internal	boolean	false	true to hide the skill from the documentation.
doc	doc[]	{}	Doc.

@species

@Target(TYPE). Defines a built-in species. The class must implement gama.api.kernel.agent.IAgent (usually by extending gama.core.agent.GamlAgent) and have a constructor (IPopulation<? extends IAgent>, int). See Developing Species.

Attribute	Type	Default	Meaning
name	String	(required)	The name of the species.
skills	String[]	{}	The skills of the species.
concept	String[]	{}	Concepts.
category	String[]	{}	Categories of the documentation.
internal	boolean	false	true to hide the species from the documentation.
doc	doc[]	{}	Doc.

@symbol

@Target(TYPE). Defines a statement, or another kind of symbol (layer, output, batch method...). The class must implement gama.api.gaml.symbols.ISymbol (usually through a statement base class) and have a constructor taking an IDescription. See Developing Statements.

Attribute	Type	Default	Meaning
name	String[]	{}	The keyword(s) of the symbol.
kind	ISymbolKind	(required)	The kind of symbol. See ISymbolKind.
with_sequence	boolean	(required)	true if the symbol can (or must) be followed by a block {...} of statements.
with_scope	boolean	true	true if the block defines its own scope. Otherwise, its temporary variables are defined in the enclosing scope.
with_args	boolean	false	true if the symbol accepts arguments (like do or create).
remote_context	boolean	false	true if the block is executed in the context of other agents, while the temporary variables of the enclosing scopes stay accessible (like ask).
breakable	boolean	false	true if the statement can be interrupted by break.
continuable	boolean	false	true if the statement can be interrupted by continue.
unique_in_context	boolean	false	true if the statement can only appear once in its enclosing statement (e.g. return).
unique_name	boolean	false	true if two statements with the same name cannot appear in the same enclosing statement (e.g. state, reflex).
concept	String[]	{}	Concepts.
category	String[]	{}	Categories of the documentation.
internal	boolean	false	true to hide the symbol from the documentation.
doc	doc[]	{}	Doc.

@test

Repeatable (grouped in @tests). Placed on an element (usually an operator), it defines a GAML test. The tests of a plugin are written in one test experiment in gaml/models/Tests/Generated From <Plugin>/models/<Plugin> Tests.gaml.

@tests ({ @test ("sqrt(4.0) = 2.0"), @test ("is_error(sqrt(-1.0))") })

Attribute	Type	Default	Meaning
value	String	(required)	The GAML code of the test. It becomes assert <value>;. Several statements can be separated by ;: the last one becomes the assertion. If the string ends with ;, no assert is added, so you can write your own assertions. Variables are local to each test.
name	String	""	The name of the test. By default it is built from the element (e.g. Operator +), and numbered if needed (Operator + (1)).
warning	boolean	false	true if a failure must only be reported as a warning.

@tests

The container of repeated @test annotations. You can write @tests({...}), or repeat @test.

Attribute	Type	Default	Meaning
value	test[]	{}	The tests.

@type

@Target(TYPE), inherited. Defines a data type. The class must implement IType (usually by extending gama.api.gaml.types.GamaType) and have a constructor (ITypesManager). Every type gets a casting operator with its name. See Developing Types.

Attribute	Type	Default	Meaning
name	String	(required)	The keyword of the type.
id	int	(required)	A unique id. For types defined in plugins, use a free value starting at IType.BEGINNING_OF_CUSTOM_TYPES (5000) and below IType.BEGINNING_OF_SPECIES_TYPES (10000).
wraps	Class[]	(required)	The Java classes of the values. The first one is the preferred class.
kind	ISymbolKind	ISymbolKind.REGULAR	REGULAR, or NUMBER for numeric types.
concept	String[]	{}	Concepts.
category	String[]	{}	Categories of the documentation.
internal	boolean	false	true to hide the type from the documentation.
doc	doc[]	{}	Doc.

@usage

@Target({TYPE, METHOD}), and used in @doc(usages = ...). Describes a particular way of using an element (e.g. one variant of an overloaded operator). A usage can also be used as a code template in the GAML editor.

Attribute	Type	Default	Meaning
value	String	(required)	The description of the usage. For templates, it is shown as a tooltip.
examples	example[]	{}	Examples of the usage (they can become tests).
pattern	String	""	Instead of examples, the content of the usage as one string (with \n and \t for the layout).
name	String	""	The name of the template in the menu.
menu	String	""	The top-level menu of the template. Use the constants of usage: GENERAL, STATEMENT, OPERATOR, MODEL, SPECIES, EXPERIMENT, DEFINITION ("Attribute"), CUSTOM, or any other name. If empty, GAMA guesses it.
path	String[]	{}	The sub-menus of the template, e.g. {"Control", "If"}. If empty, GAMA guesses it.

@variable

Can only be used inside @vars(...). Declares an attribute.

Attribute	Type	Default	Meaning
name	String	(required)	The name of the attribute.
type	int	(required)	Type id of the attribute.
of	int	0	The content type, if the attribute is a container.
index	int	0	The index type, if the attribute is a container.
constant	boolean	false	true if the attribute cannot be modified.
init	String	""	A GAML expression giving the initial value.
depends_on	String[]	{}	Attributes that must be initialized before this one.
internal	boolean	false	true to hide the attribute from the documentation.
doc	doc[]	{}	Doc.

The value is read and written by the methods annotated with @getter and @setter. The processor reports an error if an attribute is declared twice in the same class.

@vars

Placed on a skill, an agent class, a GAML class, or a value class (or interface) of a type. Lists its attributes. On a value class, the attributes are read with the . operator (e.g. my_color.red, declared in gama.api/src/gama/api/types/color/IColor.java).

Attribute	Type	Default	Meaning
value	variable[]	(required)	The attributes (see @variable).

---

Annotations defined in gama.api

These annotations are in the package gama.api.annotations of the plugin gama.api, because they refer to classes of this plugin.

@validator

@Target({METHOD, TYPE}), inherited. Gives a class that checks a statement (or an operator) at compile time, in addition to the checks made from the annotations. Example: @validator(StateValidator.class) on FsmStateStatement.

Attribute	Type	Default	Meaning
value	Class<? extends IValidator>	(required)	The validator class.

@serializer

@Target(TYPE), inherited. Gives a class that writes a statement back as GAML code.

Attribute	Type	Default	Meaning
value	Class<? extends ISymbolSerializer>	(required)	The serializer class.

@depends_on

@Target(METHOD). Placed on an operator, lists the attributes of the model that must be initialized before the operator is used (for example, the shape of the world).

Attribute	Type	Default	Meaning
value	String[]	{}	The names of the attributes.

---

Support classes

The package gama.annotations.support contains the constants used as values of the annotations.

ISymbolKind

An enum giving the kinds of symbols, used in @symbol(kind = ...), @inside(kinds = ...) and @type(kind = ...). Each value has a code:

Value	Code	Value	Code
SPECIES	0	BATCH_METHOD	9
MODEL	1	ENVIRONMENT	10
SINGLE_STATEMENT	2	SEQUENCE_STATEMENT	11
BEHAVIOR	3	ACTION	11 (same as SEQUENCE_STATEMENT)
PARAMETER	4	EXPERIMENT	13
OUTPUT	5	ABSTRACT_SECTION	14
LAYER	6	OPERATOR	15
SKILL	7	PLATFORM	16
BATCH_SECTION	8	CLASS	17
NUMBER	101	REGULAR	104
FACET	9999

NUMBER and REGULAR are the kinds of variables and types. (Older documentation used constants such as ISymbolKind.Variable.NUMBER; they no longer exist.)

ITypeProvider

Constants that compute a type from the operands of an operator (or from the owner of an attribute). They are used in type, content_type, index_type and similar attributes. For the ..._AT_INDEX constants, add the 1-based index of the operand (e.g. ITypeProvider.CONTENT_TYPE_AT_INDEX + 1).

Constant	Meaning
NONE (-13)	The type is not computed (default).
TYPE (-14)	The type of the expression itself.
BOTH / ALL (-21)	The common supertype of the operands.
TYPE_AT_INDEX (-200) + n	The type of operand n.
CONTENT_TYPE_AT_INDEX (-300) + n	The content type of operand n.
DENOTED_TYPE_AT_INDEX (-350) + n	The type denoted by operand n (e.g. a species or a type name).
KEY_TYPE_AT_INDEX (-400) + n	The key type of operand n.
KEY_AND_CONTENT_TYPE_AT_INDEX (-450) + n	A pair of the key type and content type of operand n.
FLOAT_IN_CASE_OF_INT (-1000)	float if the computed type is int.
FIRST_ELEMENT_CONTENT_TYPE (-22)	The content type of the first element of the operand (experimental).
FIRST_CONTENT_TYPE_OR_TYPE, SECOND_CONTENT_TYPE_OR_TYPE, THIRD_CONTENT_TYPE_OR_TYPE	The content type of the operand if it is a container, otherwise its type.
SECOND_DENOTED_TYPE (-32)	The type denoted by the second operand.
OWNER_TYPE, OWNER_CONTENT_TYPE, OWNER_KEY_TYPE	For attributes: the type (content type, key type) of the owner.
MODEL_TYPE, EXPERIMENT_TYPE, MACRO_TYPE, MIRROR_TYPE	The type of the model, the experiment, the macro-agent, the mirrored agents.
WRAPPED (-30)	The type of the contents of a file.
STATEMENT_TYPE (-35)	Temporary-declaring facets only: the computed type of the statement, including its selected species/target type.
INFERRED_TYPE (-36)	Temporary-declaring facets only: the statement's declared type or its value/iteration inference, preserving nested container parameters.

STATEMENT_TYPE and INFERRED_TYPE are supported in type, of, and index of @facet(declares_new_temp = true), not as general operator providers. Other negative provider IDs are not supported on these facets. OWNER_TYPE is not a substitute for STATEMENT_TYPE: it describes the owning species/operand, not the statement's computed type.

FIRST_TYPE, SECOND_TYPE, FIRST_CONTENT_TYPE, SECOND_CONTENT_TYPE, FIRST_KEY_TYPE and SECOND_KEY_TYPE are deprecated: use the ..._AT_INDEX + n constants.

IOperatorCategory

String constants for @operator(category = ...). They are the sections of the operators documentation: ARITHMETIC, LOGIC, RANDOM, STATISTICAL, COMPARISON, CASTING, COLOR, SYSTEM, EDP, SPATIAL, SHAPE, THREED, SP_STATISTICAL, SP_QUERIES, SP_PROPERTIES, SP_RELATIONS, SP_TRANSFORMATIONS, ITERATOR, CONTAINER, MATRIX, STRING, LIST, MAP, GRAPH, FILE, SPECIES, GRID, PATH, DATE, TYPE, POINT, WATER, FIPA, MAP_COMPARAISON, USER_CONTROL, TIME, DEPRECATED, DRIVING, GENSTAR, SPARQL.

IConcept

About 140 String constants for the concept attributes (IConcept.ACTION, IConcept.ARCHITECTURE, IConcept.GRAPH, IConcept.MATH, IConcept.TYPE...). They are keywords used by the search of the documentation website. Use the existing constants when possible.

IConstantCategory

String constants for @constant(category = ...): LENGTH, TIME, VOLUME, WEIGHT, SURFACE, GRAPHIC, CONSTANT, MATH, COLOR_CSS, and PREFIX_CONSTANT ("#").

Reason

An enum used by @no_test:

Value	Meaning
ALREADY_TESTED	The element is tested elsewhere, usually in GAML test models written by hand.
IMPOSSIBLE_TO_TEST	A test makes no sense or is impossible to write.
DEPRECATED	The element is deprecated.
INTERNAL	The element is internal.
NONE	No reason given (default).

Constants classes

The package gama.annotations.constants contains:

• IKeyword: the GAML keywords as String constants (IKeyword.NAME, IKeyword.REFLEX, IKeyword.FSM, IKeyword.LOCATION, IKeyword.CONTROL, IKeyword.CLASS...). Use them in annotations instead of literal strings;
• XMLElements: the names of the elements of the XML documentation generated by the processor;
• ColorCSS: the CSS colours available in GAML (#red, #aliceblue...).

Checking annotations with the developer tools

The GAMA developer tools help you find and complete missing annotations:

• GAMA > Report > Missing annotations (or GAMA > Report missing annotations... in the context menu of a plugin) builds a Markdown report from the warnings of the processor. It lists the undocumented GAML elements and the untested operators of each plugin.
• GAMA > Repair GAMA plugins > Generate missing tests writes models/Tests/Untested Operators.gaml in each selected plugin (or in all of them). The file contains one test stub for each operator reported as not tested, with its Java signature. Stubs already in the file are kept.
• Quick fixes (Ctrl+1 / Cmd+1, in the Java editor or the Problems view):
  • on "GAML: documentation missing for ...": add a @doc skeleton (for attributes, arguments and facets, the doc goes into the @variable, @arg or @facet);
  • on "GAML: operator '...' is not tested": add a failing @test("false /* TODO ... */"), mark the operator with @no_test(Reason.ALREADY_TESTED) or @no_test(Reason.IMPOSSIBLE_TO_TEST), or generate a GAML test stub.
• GAMA > Search GAML keyword... (Ctrl+Shift+Alt+K / Cmd+Shift+Alt+K) finds the Java annotation that defines a GAML keyword. Prefix the pattern to restrict the search: op:, facet:, action:, attr:, statement:.
• GAMA > Repair GAMA plugins > Rebuild annotation processor regenerates gama.processor/gama.processor.jar. Use it after you modify gama.annotations or gama.processor.