small readability improvements

- better readability of code (uppercase constants, function curly bracket on new line, removed old commented code…)
- fixed comments to match phpDoc syntax
- unambiguous construct
- default return type from api is now object, not assoc
- method to change api return type