Annotations

Annotation stands for any additional piece of information provided by developer in source code or other augmented files.
Annotations express specific properties and relations of be it either a variable,
or single code statement or a code block or a function or source file or even a whole program.
This additional knowledge is precious in number of circumstances for improving compilation in a different ways.

See syntax and examples for annotations.

Logic inference

This is a process of an annotations extracting from source code and from any accompanied data and reasoning to make decisions affecting compilation phase.

Annotations are gathered from number of inputs, such as:

{Fres/diagram-logic_inference_overview.dia}
Usual path of program compilation(depicted in the left part of the diagram) augmented by logic reasoning path(depicted in the right).
During initial phases scattered and disjoined annotations are gathered from various levels and inputs to form complete logic program.
Now reasoning runs based on gathered data and logic rules. Reasoning output directly affects compilation process in a number of ways(depicted as return arrow in the diagram).

Ways to impact compilation phase are expanded and are matter of language evolution.
As of now implemented:

In order to facilitate practically useful features as intended, annotations have to be:

• Domain specific, extendable, developer provided annotations

Compiler itself does not dictate exact set of annotations for developer to use,
but able to use custom annotations to expess desired program properties without prior changes to compiler.
Such ability is necessary to check program-specific policies and code metrics. See Annotations, for further examples.

• Explicitly control compiler

Annotations constitute convenient interface to interfere with compiler internal processes in cases
when it produces suboptimal results or even silly enough to not be able produce any at all.
Good examples are external interface or dsl

• Diffusible

Annotations in Xreate are intended for expressing information specific or useful in certain circumstances only.
Different annotations usually related to a different program aspects and it's natural way to allow different aspect's annotations
to sit in different places, to isolate responsibility and reduce manual support effors.
On the other hand, different anylis phases could produce additional(implicit) annotations along with manually provided ones to improve decisions quality.

Taking all of this into account, compiler should be able to diffuse, or blend in annotations originated from various sources seamlessly to build solid foundation for logic inference.
Such ability is cruicial to facilitate declartative_patterns, for example.

• Augmented annotations

Very close to point above is ability to connect external and independent sources of annotations unknown on the development stage.
See supervision for examples.

• Bottom up annotations

Purpose of annotations' very existing as a language construct is unquestionable if it able to conduct information impossible to
express by any other traditional programming techniques or constructs. Particularly, this is true for information which is unknown during development.
Paradoxycally speaking, annotations' very purpose and utility is to provide information which is impossbile to provide.

One example of such kind is information which is known only very lately is an enviroment where code is executing.
More precisely, library code(server) is unaware of exact particular characteristics of client code(frontend) it used by while library development.
Important ability of annotations to conduct information regarding caller code to a callee code for possible adjustemnts is called "bottom-up annotations"
meaning awareness "down" code(deep nodes in control tree) of "up" code (top nodes in control tree) particular characteristics.

See [Objectives/Optimization/component_level_optimization] as example.

• Automatic reevaluation

Any code reworking and rewriting leads to changes in annotations or relations between them,
and as a consequence leads to a different dicisions inferred by inference engine.
Such feature releases developer from burden of manually to spot and fix invalidated parts every time.
So it's good candidate to express by annotations every aspect which is broke frequentlty after code changes

• Different applicable objects

Different techniques require reasoning about different kinds of program entities be it variables or whole source files.
As of now, Xreate supports annotations for variables, single statements, code blocks and entire functions.

See also:

• Annotations
• declarative_patterns