walk needs more doc

[miner]

I got tripped up by some changes to walk (compared to the pre-1.0 version). The order of the arguments changed, which is fine -- Clojure HOFs should take the function first. The big difference is that walk is now lazy and returns the results of mapping over the directory structure. The old version was called just for side-effects (per dorun). It's not obvious from the doc-string what the walk order is so it's unclear how useful the results would be.

I think walk should document the walk order as depth-first, and add a note that it's lazy. Suggested doc-string:

"Lazily walks depth-first over the directory structure starting at 'path', calling 'func' with three arguments [root dirs files]. Returns a sequence of the results."

Also, the doc-string for iter-dir should say that it's depth-first.

[Raynes]

Looks good. I'll accept a pull request fixing the docstrings, or I'll do it myself asap.