fix reading directory hierarchies and add comments
update documentation