Improve the documentation.

The --directories flag marks a directory recursively owned by the package (#245, #293, #294)
Merge pull request #582 from ketan/improve-documentation

Improve the documentation.