Documentation needs update

[ricardobeat]

• document all accepted path formats, wildcards, etc
• explain callback logic for multiple files
• sync vs async
• common task patterns