Wie/unter welchen Umständen funktioniert das Tag <see> in Delphi-XML-Kommentaren?

Question

Ich frage mich, wie diese XML-Referenzen funktionieren, ich verstehe einfach nicht, warum sie funktionieren oder warum sie nicht funktionieren, und ich habe nichts darüber gefunden.

Hier ist ein Beispiel:

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; 

Der Link im Kommentar von TOuterClass.Log funktioniert nicht. Delphi XE5 denkt nur darüber nach und gibt dann auf.

Ein weiteres ganz einfaches Beispiel:

Unit MyUnit 

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

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

Auch dieser Link nicht funktioniert. Das Interessante daran ist: Wenn Sie einfach den XML-Kommentar auskommentieren, dann erstellt Delphi automatisch den gleichen Linktext ("MyUnit.TMyType") und es funktioniert! Das verwirrt mich wirklich.

Was kann genau diese Links verlinken auf, welche Konventionen muss ich folgen, um es, zu arbeiten und was sie nicht verlinken?

Die official documentation ist ziemlich kurz dazu:

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

Wenn es von Bedeutung ist: Ich verwende Delphi XE5, aber ich würde schätzen Hinweise, wie dies funktioniert auf jeder beliebigen Version von Delphi. Ich würde sogar Beispiele von Links schätzen, die überhaupt funktionieren (bitte fügen Sie Ihre Version von Delphi hinzu), vielleicht würde das dabei helfen, die Mechanik dahinter zu enthüllen.

bearbeiten 2014.08.25:

Ich bin zu denken beginnen, dass diese Links Link zur eigentlichen HTML-Dokumentationsdateien, die in meinem Fall, nicht existieren, weil ich für definiert nicht ein Verzeichnis Sie. Ich mache nur XML-Kommentare, um die Hinweise in Delphi IDE zu bekommen. Kann das jemand bestätigen?

Answer 1

nicht sicher, ob dies immer noch ein Problem ist, aber ich weiß, in XE3 Sie die verwenden | Zeichen zu verweisen zurück

Beispiel

Unit MyUnit 

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

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

Vielleicht ich das Problem bin Missverständnis, aber diese Syntax wird der Code Einsicht zurück verweisen lassen. Dies schließt jedoch eine Warnung erzeugen beim Kompilieren also, wenn Sie diese verwenden möchten, können Sie durch Hinzufügen {$WARN XML_CREF_NO_RESOLVE OFF}, um den Code um die Warnung auszuschalten.

Ich habe Screenshots, aber ich bin nicht in der Lage, sie noch zu veröffentlichen. Aber Sie können das selbst versuchen

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.