add clearer doc strings, still unsure about predicating functions on dir
var... should I add a parameter that forces the user to declare a dir?
or is that too annoying -- it seems to be a tradeoff