added documentation to my changes
additional comments
well, it's a terrible api but it works