Docblock annotations are deprecated, and now say so
Parsing a docblock annotation triggers a runtime deprecation, once per Generator run and only
when an annotation is actually parsed — a project that has moved to attributes still has
docblocks everywhere and stays quiet.
Most people will see nothing. trigger_deprecation() is suppressed by design, so the notice
surfaces only where a deprecation handler is listening for one. It is a heads-up, not a change
of behaviour.
The README has recommended attributes over annotations since 4.8; the code now agrees. Docblock
support is marked @deprecated and removed in 8.0 — it keeps working unchanged through v7.
Deprecation markers name the version that removes them
ROADMAP.md said classic code is marked in v6 and removed in v7, and the markers in src/ did
not say either. The rule is now written down — a marker names the version that removes the
thing, and nothing is removed before the version its marker names — and every marker in the
tree follows it.
Where that lands: anything classic depends on goes when classic does, including the sentinels
Generator::UNDEFINED and Generator::isDefault(), which classic processors and hand-built
annotation objects both use.
Spec pipeline
Specification::buildPathItemHierarchy() answers "which PathItems govern this class" — the
walk that resolves a controller's prefix, tags and security through its ancestors. It is what
the augmenter now uses in the several places that each had their own copy, and it is available
to anything else built on a Specification. Resolving path-level output no longer re-walks the
chain for every operation.
The pipeline also has a Why spec attributes?
page, leading with the thing classic attributes cannot do at all — building a document from
values, with nothing to scan.
Changes
- docs(Contributing): write down what earns a patch, minor or major by @DerManoMann in #2214
- feat(Specification): one PathItem hierarchy helper instead of five walks by @DerManoMann in #2215
- docs(Roadmap): say when classic goes, and mark what the file says is marked by @DerManoMann in #2216
- docs(Guide): add a why-spec page, and stop three places underselling it by @DerManoMann in #2217
Full Changelog: 6.10.0...6.11.0