Referenz-Präfixe in .NET XML-Dokumentation
-
13-09-2019 - |
Frage
Ich habe versucht worden, vollständig zu dokumentieren, alle Arten, Methoden, Eigenschaften usw. von einer Klassenbibliothek unter Verwendung von XML-Kommentare aber haben eine merkwürdige Wirkung Beteiligung des cref
Attribut (verwendet von see
Tags zum Beispiel) ausgeführt werden. Going durch die Beratung von dieser MSDN-Seite sowie nach verschiedenen anderen Beispiele auf MSDN und anderen Websites, scheint es, dass, wenn man einen Referenzwert mit dem cref
Tag gibt, muss sie mit einem bestimmten Marker vorangestellt werden, die die refence klassifiziert (wie ‚T:‘ für Art und ‚M:‘ für Methode) .
Mit Microsoft Sandburg, aber ich habe festgestellt, dass diese Präfixe von verpassten gibt es einen Effekt in der erzeugten Dokumentation (CHM-Hilfedatei in diesem Fall). Einschließlich Präfixen (in allen Situationen, die ich glaube), wird die Referenz auf der Seite als fettgedruckter Text gemacht ... Doch discluding das Präfix der Referenz als Anker (Link) an der zuständigen Seite innerhalb der API-Referenz gemacht wird. Es scheint ziemlich seltsam für mich, dass die empfohlene Methode von prefixing (alle?) Referenzen ist die am wenigsten brauchbares Ergebnis zu geben - warum sollte die Referenz als fett in einem Fall und in einem anderen verknüpft gemacht werden? Ich würde es begrüßen, wenn jemand etwas Licht auf diesem verschütten könnte.
Lösung
Dies scheint ein Fehler in Sandburg
Welche Version von Sandburg sind Sie mit?
Wie gesagt jüngste Diskussionen scheinen zu zeigen, zumindest für Systemtypen ist die vorgeschlagene Methode tatsächlich zu vermeiden, dass die qualifizierten Namen verwenden, da die in dieser Antwort gesetzt Beispiele, die die T fielen: und M:. ganz Ihre Verwirrung ist daher nicht unerwartet oder ungewöhnlich
Diese Dokumentation impliziert stark, dass der Compiler, wo er Stelle, welche Art / Methode / constant Sie zeigen die Präfixe für Sie einfügt. Haben Sie das in der XML-prüfen?