Perf & refactor

@pavelgj could you please review this (might be easier to review commit by commit).

The overall goal is to make the code easier to understand - at least for me :)

It contains:
- style: adding return types, folowing Dart coding standards,
- refactor: try to make the code easier to read,
- perf: mainly removing recursion for a few methods - IMO the resulting code is easier to grasp,
- doc: add some doc & fix other parts