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

Интересно, как работают эти 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. Кто-нибудь может это подтвердить?

Ответы

Ответ 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.