address review comments, will be merged later:

add some comments to distinguish between helper functions
and functions which are called directly from LUA