Docs, argument annotaions 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. 
Can you remove unneeded empty lines in all comment blocks? By "unneeded" I mean lines at the beginning and end of the comment block.