Fix use of "$refs" (zircote#959)

Also adds `swagger-cli` as second validator for example specs.

Limit summary/description augmenting to primary annotations (zircote#955

)

When extracting summary/description from a docblock this should only
apply to the primary / top-level annotation associated with the
docblock.

Also includes some minor cleanup in YAML formatting and undocumented
properties.

Regression: Fix traits without class-level phpDocs (zircote#941)

Fix crash with a trait without schema

Add Generator class for OO use (zircote#928)

Also starts work on making `src/functions.php` obsolete.

* `Generator` class wraps all config/settings in a single place
* `UNDEFINED` const migrated to `Generator::UNDEFINED`
* PHP token code refactored to avoid having to use custom polyfill
* Migrate all code to use `Generator`
* Extend documentation on how to use swagger-php from PHP (using the
  `Generator` class)
* Deprecate all static API elements - `scan()` function,
  `Analyser::$whitelist` and `Analyser::$defaultImports`

Merge pull request zircote#882 from Tobion/patch-1

Fix PHP 8 compatibility in 2.x

doc: Updated maintainers

Merge pull request zircote#830 from DerManoMann/php8-token

Add support for new PHP8 T_NAME_xxx token

Released 2.0.16

feat: info->version must be a string

Prevents the "Structural error at info.version
should be string" validation error

Release 2.0.15

- Support for PHP7.4 zircote#741