XML-Kommentare – Sollten Referenzen vollständig qualifiziert sein?

Question

Grundsätzlich: Wann ist es wirklich notwendig (wenn überhaupt), eine vollständig qualifizierte XML-Datei zu verwenden? Siehe Referenz:

<see cref="T:MyNamespace.Sub.MyType"/> //Option 1
<see cref="T:MyType"> //Option 2

Und wie sieht es mit Verweisen auf die .NET Framework-Objekte aus?

<see cref="T:System.Collections.Generic.ICollection{T}"/> //Option 1
<see cref="T:ICollection{T}"/> //Option 2

Ich verstehe, dass vollständig qualifizierte Elemente es Microsofts Sandcastle immer ermöglichen werden, die Dinge richtig zu verknüpfen, aber ist es notwendig, dass alles vollständig qualifiziert ist?

---

Randnotiz:Wird Microsoft Sandcastle in der Lage sein, auf die .NET Framework-Hilfedateien zu verlinken, oder verschwende ich meine Zeit mit der Referenzierung? <see cref="T:System.Collections.Generic.ICollection{T}"/>?

Answer 1

Beide Joseph und ben berühren nützliche Punkte, aber ich denke, mein neues Sandcastle-Erfahrung kann hilfreich sein:

.

1. Wenn Sie Ihr Projekt kompilieren, zeigt visuelle Studio in der Regel, ob Ihre Referenz durch die Ausgabe einer Warnung gültig ist, wenn er keine Referenz in Ihren Doc-Kommentaren lösen kann, ob dies ein Verweis auf Ihre eigenen Typen ist oder Systemtypen (und VS ehren Ihre "Verwendung" -Anweisungen).

2. In dem Szenario, ein lokaler Typ zu haben, der einen Systemtyp maskiert, gibt es zwei Fälle, um zu berücksichtigen: Ihre Unterschrift qualifiziert Ihren Typ eindeutig (abgedeckt von (1) oben), oder Ihre Unterschrift wird genau ein Systemtyp dupliert. Der letztere Fall erfordert eine explizite Disambiguation, indem er den Namen vollständig qualifiziert hat.

3. Sie berührt mit der Verwendung von explizit anspezifizierenden Präfix Member-Type (z. B. "t: superwidget"), dies ist jedoch wichtiger als die meisten Menschen, die erkennen: Wenn Sie einen Mitgliedstyp verwenden Präfix dann sind vollständig qualifizierte Namen erforderlich . Dies ist tatsächlich auf MSDN dokumentiert, jedoch in sehr feiner Druck - siehe Verarbeitung der XML-Datei . Und um die Angelegenheiten schlimmer zu machen, wenn Sie den vollständig qualifizierten Namen auslassen, erhalten Sie keine Warnung bei der Bauzeit (!); Im letzten Sandcastle-Rendering wird einfach kein Link erzeugt. Es gibt andere Probleme, wenn Sie ein Mitgliedstyp-Präfix explizit angeben - siehe desimbiguating- und auflösende Referenzen Abschnitt meines Artikels über praktische Sandcastle-Tipps, Taming Sandcastle: Ein .NET-Programmieranleitung für dokumentieren Sie Ihre Code .

Answer 2

Ich kann nicht für Sandcastle sprechen, aber aufgrund meiner Erfahrung mit anderen Tools, z. B.Laut ReSharper muss ein Typ anscheinend qualifiziert werden, wenn er a) nicht im Gültigkeitsbereich liegt oder b) von einem anderen Typ überschattet wird, der eher lokal definiert ist.

Mit anderen Worten, wenn Sie es sind using System.Collections.Generic, dann müssen Sie sich nicht qualifizieren ICollection{T}.Wenn Sie zufällig Ihre eigenen definieren ICollection{T} Schnittstelle in derselben Datei, jedoch Sie Wille Ersteres muss man qualifizieren (sowie auch Letzteres, wenn man darüber nachdenkt).

Answer 3

Sie verschwenden Ihre Zeit nicht in der generakoditicetagcode-ing den Rahmen, meiner Meinung nach.Der Visual Studio-Hilfe-Anbieter sollte in der Lage sein, die Laufzeit abzufangen und zu interpretieren, wenn der Anruf für das Hilfethema erfolgt ist.Ich habe es kürzlich nicht genutzt, aber es hatte in der Vergangenheit ziemlich schön gearbeitet.

Um sich vollständig zu qualifizieren, wird es in den meisten Szenarien nicht benötigt, hängt jedoch von Ihren Rennings ab, wie Ben hat erwähnt .So lange das, was Sie referenzieren, in Umfang ist (und entweder sollten Sie sein, da Sie es wahrscheinlich verwenden, wenn Sie es verwenden, wenn Sie es referenzieren, oder Sie sollten die Verwendung hinzufügen, damit Ihr Code nicht das vollständig qualifizierte Formular verwendet)Nur der Typ sollte ausreichen.