Docs, argument annotations and PSR-2 fixes

This PR is mostly function documentation. I've added type annotation on some function arguments. We should use type annotation as much as we can. I added those I was sure of. Please make sure I'm correct.