delphi - 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”)并且它可以工作!这真的让我很困惑。

这些链接到底可以链接到什么，我必须遵循哪些约定才能使其正常工作，以及它们不能链接到什么？

official documentation对此相当简短:

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

如果它有任何重要性的话:我正在使用Delphi XE5，但我希望得到关于它如何在任何版本的Delphi 上工作的提示。我什至希望能提供实际有效的链接示例(请包括您的 Delphi 版本)，也许这将有助于揭示其背后的机制。

编辑2014年8月25日:

我开始认为这些链接链接到实际的 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.