[FLINK-4203] [table] [docs] Improve Table API documentation

[twalthr]

Thanks for contributing to Apache Flink. Before you open your pull request, please take the following check list into consideration.
If your changes take all of the items into account, feel free to open your pull request. For more information and/or questions please refer to the How To Contribute guide.
In addition to going through the list, please provide a meaningful description of your changes.

• General
  • The pull request references the related JIRA issue ("[FLINK-XXX] Jira title text")
  • The pull request addresses only one issue
  • Each commit in the PR has a meaningful commit message (including the JIRA id)
• Documentation
  • Documentation has been added for new functionality
  • Old documentation affected by the pull request has been updated
  • JavaDoc for public methods has been added
• Tests & Build
  • Functionality added by the pull request is covered by tests
  • mvn clean verify has been executed successfully locally or a Travis build has passed

This PR improves the documentation of the Table API a bit. It adds...

• Reserved Keywords
• Description of built-in Scalar Functions
• SQL BNF grammar
• Description of types
• Small fixes

There was also a "substring()" documentation mistake that is corrected in this PR.

[twalthr]

I will merge this now. The doc is still not perfect but we can further improve it in the future.