Delphi XE3 and deprecated

Delphi XE3 and deprecated

Deprecated is great for gradually shifting out code that you want to remove, but it has some syntactical personality issues.

Example 1
unit MyUnit;
interface
type
  TMyType = class (TSomeType)
    procedure InnocentBystander;
    procedure MyProc;  deprecated 'Use SomeOtherProc instead';
  end;

Note the semicolon before deprecated.
A call to MyProc will give a warning

[dcc32 Warning] Main.pas(xxx): W1000 Symbol 'MyProc' is deprecated: 'Use SomeOtherProc instead'

Example 2
unit MyUnit;
interface
type
  TMyType = class (TSomeType)
    procedure InnocentBystander;
    procedure MyProc; 
  end deprecated 'Use TMyOtherType instead';

Note the awkward location, and no semicolon.
A reference to TMyType will give a warning

[dcc32 Warning] Main.pas(xxx): W1000 Symbol 'TTMyType' is deprecated: 'Use TMyOtherType instead'

Example 3
Combining 1 and 2 almost works!
unit MyUnit;
interface
type
  TMyType = class (TSomeType)
    procedure InnocentBystander;
    procedure MyProc; deprecated 'Use SomeOtherProc instead';
  end deprecated 'Use TMyOtherType instead';

It's almost like the compiler can't make up it's mind about which deprecated to use, and in the end refuse the code

[dcc32 Error] MyUnit.pas(xxx): E1030 Invalid compiler directive: 'DEPRECATED'
[dcc32 Warning] Main.pas(xxx): W1000 Symbol 'TMyType is deprecated: 'Use TMyOtherType instead'
[dcc32 Warning] Main.pas(xxx): W1000 Symbol 'InnocentBystander' is deprecated
[dcc32 Warning] Main.pas(xxx): W1000 Symbol 'MyProc' is deprecated

Example 4
unit MyUnit deprecated 'Text explaining why';
interface
type
  TMyType = class (TSomeType)
    procedure InnocentBystander;
    procedure MyProc; deprecated 'Use SomeOtherProc instead';
  end deprecated 'Use TMyOtherType instead';

No semicolon, and any reference to the unit will say

[dcc32 Warning] main.pas(xxx): W1006 Unit 'MyUnit' is deprecated
but it doesn't emit the 'Text explaining why'.

Try to find the documentation for this!