timhunt has made some suggestions about improving the \core\deprecated usage. Jun has also noted a few further things to add.

In summary:

• we should require information on the replacement of the deprecated item
• we should re-order the constructor params accordingly
• we should try to get the 'owner' of the attributer rather than have to specify it manually
• we should emit a deprecation notice for any part of a class if that class itself is deprecated

Now items 1, and 2 are easy and not too controversial.

Item 3 is marginally harder and more controversial. PHP Attributes do not provide any native way to get information about the 'source' of an attribute. Therefore the only way to do so is to either:

• inject it in via a setter on the attribute
• not modify the attribute but keep the reference within the code that loads and needs it

The first option is not ideal in terms of doing the right thing with regards the use of Attributes, but it is drasticalyl simpler.
The latter option is more complex and requires us to either double-handle the reference to have it generate both the Attribute, and a string reference (this can't be done consistently from the \Reflector class), or to add another class for deprecated items which contain a reference to the source.

Item 4 is also not too hard, but we just need to make a decision on which takes precedence when both a class, and a child of that class are deprecated.

Proposed solution

1) We will require the replacement information to be provided
2) We will re-order the constructor params so that the replacement is first
3) We will not allow the owner to be specified manually, but will instead create a new deprecated_with_reference class which extends the deprecated attribute class, and adds a new string $owner required parameter. This is returned from the \core\deprecation methods and the emitter will emit the owner if possible.
4) We will emit a deprecation notice for any part of a class if that class itself is deprecated. The class deprecation notice will be emitted if both a class and a child of that class are deprecated.