Add documentation to the main 'Interflow' class and refactor some APIs

[kyouko-taiga]

This PR is simply adding documentation and renaming parts of the internal API for clarity.

[WojciechMazur]

Looks good so far, I've answered to the questions left in comments

[WojciechMazur]

In this context it stand for ThreadLocal. All of these methods are simple accessor for thread local value of given type, eg. A Thread Local nir.Fresh used to create new SSA identifiers. ThreadLocal values can be used when releaseMode=Debug as it allows for parallel optimisation of NIR by applying only a subset of optimisations. In other modes (ReleaseX) there's currently only a 1 thread performing optimization pass.

[kyouko-taiga]

Is it relevant to keep the Tl suffix in these methods then? It seems to me like it's simply a property that should be documented in the methods. Besides, we don't have any non thread local counterparts to these methods, suggesting that the qualification is perhaps superfluous.

[kyouko-taiga]

This is kind of a performative comment. It would be nice if we could describe what a scope is more precisely.

[WojciechMazur]

ScopedVar is a list a stack-like variable which can be appended when entering some scope and removed from the stack when existing the scope. Eg.

scoped(currentDefn := Foo):
  currentDefn.get // yields Foo
  scoped(currentDefn := Bar): 
    currentDefn.get // yields Bar
  currentDefn.get // yield.Foo  

These are uses to preserve current state when entering some nested area of code without usage of global variables and manually reasignnning them with old value.

In case of currentFreshScope thats a ThreadLocal[ScopedVar[nir.Fresh]] so each thread has it's own stack of nir.Fresh generators. When it starts to inline a method it would create a new nir.Fresh on top of the stack and would use it in the MergeProcessor. When it's done it would pop this value.

[kyouko-taiga]

@WojciechMazur I need your lights here.

[WojciechMazur]

Entry is a root symbol from which we should start visting the methods.
Typically it would be the main method symbol.
In case of using ScalaNative to create a library entry would be every method annotated with @exported found on the classpath.

There also exist a synthetic entries - for example a list of symbols that might not be directly reachable from the organic roots, but might be required in optimizer or in lowering stage (see Lower.depends, Generate.depends, Interflow.depends)