adding some documentation, reorganizing some functions, some performance tweaks