updating PHPDoc for PHPStorm and other IDE

here we go again ^^
a clean commit and pull request

only changed doc comments and one return

Edit:
dont know how to get rid of the last commits -_-
29d84bf is the right commit
please ignore the others