Improve attr documentation

This commit fixes #738, it also adds new signatures and more
detailed explanation to the inner workings of attr.
Merge pull request #741 from mucaho/recent_docs

Improve attr documentation