Augment Flymake API for third-party extensions

Augment Flymake API for third-party extensions

See
https://lists.gnu.org/archive/html/emacs-devel/2017-10/msg00619.html

* doc/misc/flymake.texi (Flymake error types): Rewrite
example.
(Flymake utility functions): Augment with new API.

* lisp/progmodes/flymake.el (flymake-diagnostics): New function.
(flymake--diag-accessor): New helper macro.
(flymake-diagnostic-buffer, flymake-diagnostic-text)
(flymake-diagnostic-beg, flymake-diagnostic-end)
(flymake-diagnostic-backend): Accessors for diagnostic objects.
(flymake--overlays): Use flymake-diagnostic property.
(flymake--highlight-line): Simplify.  Only set
flymake-diagnostic property.
(flymake--handle-report, flymake-goto-next-error): Use
flymake-diagnostic property.
(flymake-show-diagnostic): Use diagnostic object.
(flymake--diagnostics-buffer-entries): Use
flymake-diagnostics.