==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.

NOTE: Beyond that, there are implicit annotations automatically inferred from source code by various analyses phases to express useful insights regarding analised code. 
Such annotations do not exposed directly to a developer but accessed and used internally at reasoning phase.

See [[Syntax/Annotations|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:

|Explicit source annotations | Annotations provided by code authors in order to explictily affect on compilation. See [[Syntax/Annotations]] for details |
|Annotation rules | Extracting rules from source code and from any other accompanied data to control reasoning and annotations propagation.  See [[Syntax/Annotations#annotation-rules]] for details|
|Code analysis	| {TODO: provide links}. Number of different code analyses provide data implicitly inferred from source code |
|Supervision annotations| Annotations to reflect current external requirements and overall environment state where compilation took place either on perating mode- or OS- or computer- or even network-level. See [[Concepts/supervision]] for details|
	
{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:

|Context-based specialization| Exact function variant is picked up during compilation based on context. See [[Concepts/context]] for details|
|Container implementation| Exact container data implementation is picked up during compilation based on container usage. See [[Concepts/containers]] for details|

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 [[Syntax/Annotations#annotation-rules]], 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 [[Syntax/Interfaces/extern_c| external interface]] or  [[Concepts/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 [[Articles/declartative_patterns#preferences]], 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 [[Concepts/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:
 * [[Syntax/Annotations]]
 * [[Articles/declarative_patterns]]