Improve attr documentation

This commit fixes #738, it also adds new signatures and more
detailed explanation to the inner workings of attr.