如何/在何种情况下Delphi xml注释中的<see>标签实际上有效？

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.