How/under which circumstances does the <see> tag in Delphi xml comments actually work?

Question

I wonder how these XML references work, I'm just not getting why they work or why they don't work and I found nothing about that.

Here's an example:

type
  TOuterClass= class
  strict private
    type
      TLogger = class
      public
        /// <summary>adds a log entry</summary>
        /// <param name="Msg">text to log</param>
        procedure Log(const Msg: string);
      end;
  strict private
    FLogger: TLogger;
  public
    /// <summary>adds a log entry</summary>
    /// <param name="Msg">text to log</param>
    /// <remarks>just calls <see cref="TOuterClass.TLogger.Log" />
    /// </remarks>
    procedure Log(const Msg: string);

    property Logger: TLogger read FLogger;
  end;

The link in the comment of TOuterClass.Log doesn't work. Delphi XE5 just thinks about it and then gives up.

Another quite simple example:

Unit MyUnit

type
  /// <summary>MyType Comment</summary>
  TMyType = reference to procedure;

/// <param name="MyTypeParam"><see cref="MyUnit.TMyType" /></param>
procedure MyProcedure(MyTypeParam: TMyType);

Again, this link doesn't work. The interesting thing about it is: If you just comment out the xml comment, then Delphi auto-creates just the same link text ("MyUnit.TMyType") and it works! That's really confusing me.

What exactly can these links link to, which conventions must I follow to get it to work, and what can't they link to?

The official documentation is rather short on this:

<see> Reference to a specific type, symbol, or identifier

If it is of any importance: I'm using Delphi XE5, but I would appreciate hints on how this works on any version of Delphi. I'd even appreciate examples of links that actually work at all (please include your version of Delphi), perhaps that would help in revealing the mechanics behind it.

Edit 25.08.2014:

I'm beginning to think that these links link to the actual html documentation files, which, in my case, don't exist because I don't have a directory defined for them. I'm just doing XML-comments to get the hints in Delphi IDE. Can anyone confirm this?

Answer 1

Not sure if this is still an issue but I know in XE3 you can use the | character to reference back

Example

Unit MyUnit

type
  /// <summary>MyType Comment</summary>
  TMyType = reference to procedure;

  /// <param name="MyTypeParam"><see cref="MyUnit|TMyType" /></param>
  procedure MyProcedure(MyTypeParam: TMyType);

Maybe I am misunderstanding the issue but this syntax will allow the code insight to reference back. This does however create a warning when compiling so if you want to use this you can turn off the warning by adding {$WARN XML_CREF_NO_RESOLVE OFF} to the code.

I have screen shots but i am unable to post them yet. But you can try this yourself

unit Unit2;

interface

uses
  Winapi.Windows, Winapi.Messages, System.SysUtils, System.Variants, System.Classes, Vcl.Graphics,
  Vcl.Controls, Vcl.Forms, Vcl.Dialogs;

type
  TForm2 = class(TForm)
    procedure FormCreate(Sender: TObject);
  private
    { Private declarations }
  public
    { Public declarations }
  end;

  /// <summary>MyType Comment</summary>
  TMyType = reference to procedure;

  /// <summary>This is MyProcedure</summary>
  /// <param name="MyTypeParam"><see cref="Unit2|TMyType" /></param>
  procedure MyProcedure(MyTypeParam: TMyType);

var
  Form2: TForm2;

implementation

{$R *.dfm}

procedure TForm2.FormCreate(Sender: TObject);
begin
 //Call MyProcedure
 MyProcedure(nil);
end;

end.