PHP attributes are a useful documentation tool, but they are a terrible documentation strategy on their own. That is the short version.
The appeal is obvious. Attributes live next to the code. They are structured, machine-readable, and hard to ignore during implementation. For Laravel and PHP teams building APIs, policies, commands, or internal frameworks, that sounds like the perfect answer to documentation drift.
It is not.
Attributes are excellent for capturing metadata close to the code. They are weak at explaining intent, tradeoffs, workflow, and reader context. If you treat them as the whole documentation system, you usually end up with reference output that is technically populated but editorially useless.
My recommendation is simple: use attributes as a source layer, not as the finished docs. They are best when they feed a stronger documentation system that still has structure, narrative, and human judgment.
