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?

Argos

It might be that it only supports local references. Try go get the DocInsight guys involved here: they seem to know all about how this is supposed to work. – Acarid

That's a good point, but how do I get the DocInsight guys involved? – Argos

Ping Baoquan Zuo (: @BaoquanZuo (Edit: hmm: that @ didn't work) – Acarid

Sorry, but I have to ask again, how can I ping a user? I'm brand new to StackOverflow, searched and found nothing. I didn't even find a link to pm another user... am I blind or is that a somewhat hidden feature, or is it just not yet accessible for me with just 25 reputation from today? Sorry for the newbie stuff... – Argos

@Argos - There's no pinging. – Moncada

@SertacAkyuz I found the pinging through the help of your link to the FAQ - it's only one more click from your link :-) – Argos

Unfortunately pinging only works for previous commenters. So this is not the way to get [Baoquan Zuo] involved. – Argos

@Argos I figured: that's why I put the (Edit: hmm: that @ didn't work) in (; I've asked Baoquan Zuo to look at this at his convenience. – Acarid

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.

Turnpike

The issue persists, I'm just ignoring it in the moment, producing xml comments that don't work... So I'll try it on Monday and report back. – Argos

That Syntax doesn't work at all, it produces a Warning: "W1206 comment on 'OnOpsChanged' has cref attribute 'TCMTSyncLogger|EndOp' that could not be resolved" – Argos

This syntax does works for the code insight in Delphi XE3. It does produce the warning though. – Turnpike

This worked well in Delphi 10.1 Berlin and didn't produce said warning. – Disconsolate

Confirmed. Worked for me in Delphi 10.1 upd 2 – Coopt

Answer 2

The following works for me XE8.

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

Protozoon