[FLINK-3728] [tableAPI] Improve error message and documentation for unsupported SQL features.

[fhueske]

This PR

1. extends the Table API / SQL documentation and lists known limitations.
2. improves the error message in case Calcite cannot fails to optimize the program because it includes unsupported features.

• 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

[fhueske]

Will merge this later today, unless somebody objects.

[vasia]

Also looks good! +1.

[fhueske]

Thanks :-)

[fhueske]

merging