Как / при каких обстоятельствах тег <see> в комментариях Delphi xml на самом деле работает?

Question

Интересно, как работают эти XML-ссылки, я просто не понимаю, почему они работают или почему они не работают, и я ничего не нашел об этом.

Вот пример:

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;

Ссылка в комментарии TOuterClass.Log не работает. Delphi XE5 просто думает об этом и затем сдается.

Еще один довольно простой пример:

Unit MyUnit

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

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

Опять же, эта ссылка не работает. Интересная вещь об этом: если вы просто закомментируете комментарий xml, то Delphi автоматически создает точно такой же текст ссылки ("MyUnit.TMyType"), и это работает! Это действительно смущает меня.

На что именно могут ссылаться эти ссылки, на какие соглашения я должен следовать, чтобы заставить его работать, и на что они не могут ссылаться?

Официальная документация довольно коротка по этому вопросу:

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

Если это имеет какое-либо значение: я использую Delphi XE5, но я был бы признателен за советы о том, как это работает на любой версии Delphi. Я бы даже оценил примеры ссылок, которые действительно работают вообще (пожалуйста, включите вашу версию Delphi), возможно, это поможет раскрыть механику, стоящую за ней.

Изменить 25.08.2014:

Я начинаю думать, что эти ссылки ссылаются на фактические HTML-файлы документации, которых, в моем случае, не существует, потому что у меня не определен каталог для них. Я просто делаю XML-комментарии, чтобы получить подсказки в Delphi IDE. Кто-нибудь может это подтвердить?

Answer 1

Не уверен, что это все еще проблема, но я знаю, что в XE3 вы можете использовать | символ для ссылки назад

пример

Unit MyUnit

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

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

Может быть, я неправильно понимаю проблему, но этот синтаксис позволит взглянуть на код обратно. Это, однако, создает предупреждение при компиляции, поэтому, если вы хотите использовать это, вы можете отключить предупреждение, добавив {$WARN XML_CREF_NO_RESOLVE OFF} к коду.

У меня есть скриншоты, но я пока не могу их опубликовать. Но вы можете попробовать это сами

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.

Answer 2

У меня работает XE8.

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