Improvements to mkdir_recursive

r? @brson This hopefully addresses your concerns about the termination condition, and adds more tests. With a bonus documentation commit.