Wie entkomme ich Zeichen in c # -Kommentaren?

112

Ich habe heute festgestellt, dass ich nicht weiß, wie ich Zeichen in Kommentaren für C # entkommen kann. Ich möchte eine generische C # -Klasse dokumentieren, kann aber kein richtiges Beispiel schreiben, da ich nicht weiß, wie ich den Zeichen <und entkommen kann >. Muss ich <und verwenden >? Ich mag es nicht, wenn dies der Fall ist, da ich es einfach machen möchte, den Kommentar im eigentlichen Dokument zu lesen, damit ich kein Codedokument generieren muss, um den Beispielcode lesen zu können.

c#

— Tomas Jansson
quelle

1

Könnten Sie einen Beispielkommentar zeigen?

— BoltClock

Mögliches Duplikat der XML-Zeichenfolge in einem C # -Zusammenfassungskommentar

— Mark Pim

1

@Mark: Sie haben Recht, aber es ist nicht nur XML ... Ich habe versucht, ein Beispiel für Generika zu schreiben, das nicht XML ist, sondern '<' und '>' verwendet. Die Lösung ist jedoch für beide gleich.

— Tomas Jansson

Welche mögliche Entschuldigung hat Microsoft angesichts der Beliebtheit von Vorlagen in C ++, Java, C # ... für die Verwendung von halbgebackenen XML-Trennzeichen? Der übliche Mangel an Klarheit und Weitsicht.

— Rick O'Shea

141

Wenn Sie Zeichen in XML - Kommentare entkommen müssen, müssen Sie die Zeichenentitäten verwenden, so <müssten wie zu entkommen <, wie es in Ihrer Frage.

Die Alternative zum Entkommen ist die Verwendung von CDATAAbschnitten mit dem gleichen Effekt.

Wie Sie bemerkt haben, würde dies eine gut aussehende Dokumentation ergeben, aber einen schrecklichen Kommentar zum Lesen ...

— Oded
quelle

19

Nur als Referenz <wäre <und >wäre >. Als BeispielList<string> myStringList = new List<string>();

— Arvo Bowen

@ArvoBowen Nur für den Fall, dass jemand das Offensichtliche verpasst, steht lt/ gtfür "kleiner als" / "größer als".

— Lukas Juhrich

1

Interessanterweise muss nur <entkommen werden <, >kann bleiben wie es ist : List<string> myStringList = new List<string>();. Zumindest funktioniert dies in Intellisense. Seltsamerweise CDATA funktioniert nicht in Intellisense. Ich habe nicht überprüft, wie es in automatisch generierten Dokumenten aussieht.

— Peter Huber

Kann bestätigen, dass VS 2013 nicht CDATAin Intellisense gerendert wird. <macht den Kommentar schwer zu lesen.

— Alex

52

In einfachen C # -Kommentaren können Sie ein beliebiges Zeichen verwenden (außer */wenn Sie den Kommentar mit /*oder das Zeilenumbruchzeichen mit begonnen haben //). Wenn Sie XML-Kommentare verwenden, können Sie einen CDATA-Abschnitt verwenden , um '<' und '>' Zeichen einzuschließen.

Weitere Informationen zu XML-Kommentaren in C # finden Sie in diesem MSDN-Blogartikel .

Beispielsweise

/// <summary>
/// Here is how to use the class: <![CDATA[ <test>Data</test> ]]>
/// </summary>

— Mark Pim
quelle

12

Sie haben wahrscheinlich Recht, wenn Sie gut aussehende HTML-Dokumente erstellen möchten, aber ich bin interessanter daran, die Intellisense-Tipps in VS richtig zu machen, und dafür muss ich anscheinend XML-Escape verwenden. Aber +1 für die Alternative.

— Tomas Jansson

2

Hmm, unleserlicher Maschinenmüll in meinen Kommentaren hilft nur, wenn wir uns die Zeit nehmen, unsere Dokumentdatei zu erstellen, wenn die große, große, große (habe ich große erwähnt?) Mehrheit der Anwendungsfälle die Kommentare in der Quelle liest (vorzugsweise eine Schnittstelle). .

— Rick O'Shea

19

Sie sagten: "Ich möchte es einfach machen, den Kommentar im eigentlichen Dokument zu lesen." Genau.

Entwickler verbringen den größten Teil ihres Lebens im Code und lesen keine automatisch generierten Dokumente. Diese eignen sich hervorragend für Bibliotheken von Drittanbietern wie Diagramme, jedoch nicht für die interne Entwicklung, bei der wir mit dem gesamten Code arbeiten. Ich bin schockiert, dass MSFT keine Lösung gefunden hat, die Entwickler hier besser unterstützt. Wir haben Regionen, die Code dynamisch erweitern / reduzieren ... warum können wir keinen direkten Rendering-Schalter für Kommentare erstellen (zwischen Rohtext und verarbeitetem XML-Kommentar oder zwischen Rohtext und verarbeitetem HTML-Kommentar)?. Scheint, als hätte ich einige elementare HTML-Funktionen in meinen Methoden- / Klassenprologkommentaren (roter Text, Kursivschrift usw.). Sicherlich könnte eine IDE ein wenig HTML-Verarbeitungszauber wirken, um Inline-Kommentare zu beleben.

Meine Hack-of-a-Solution-Lösung : Ich ändere '<' in "{" und '> "in"} ". Das scheint mich für den typischen Kommentar zum Verwendungsstil eines Beispiels abzudecken, einschließlich Ihres spezifischen Beispiels. Unvollkommen, aber pragmatisch angesichts des Lesbarkeitsproblems (und der Probleme mit der Färbung von IDE-Kommentaren, die bei Verwendung von '<' auftreten)

— Dave
quelle

5

Ihr "Hack einer Lösung" scheint korrekter zu sein als Sie denken. Demnach erkennt der Compiler-Erkenner geschweifte Klammern als spitze Klammern und bindet sie korrekt .

— RubberDuck

7

C # XML-Kommentare werden in XML geschrieben, sodass Sie normales XML-Escape verwenden würden.

Beispielsweise...

<summary>Here is an escaped &lt;token&gt;</summary>

— Bob Black
quelle

5

Ich habe eine lebenswerte Lösung für dieses Problem gefunden, die einfach zwei Beispiele enthält: eine schwer lesbare Version in den XML-Kommentaren mit Escape-Zeichen und eine andere lesbare Version mit herkömmlichen //Kommentaren.

Einfach aber effektiv.

— HolySamosa
quelle

0

Besser als die Verwendung von {...} ist die Verwendung von ≤ ... ≥ (kleiner als oder gleich Vorzeichen, größer als oder gleich Vorzeichen, U2264 und U2265 in Unicode). Sieht aus wie unterstrichene spitze Klammern, aber definitiv Winkelklammern! Und fügt Ihrer Codedatei nur ein paar Bytes hinzu.

— Mick Bruno
quelle

0

Versuchen Sie es noch besser mit U2280 und U2281 - kopieren Sie sie einfach aus der Liste der Unicode-Zeichen (Abschnitt mit mathematischen Operatoren) und fügen Sie sie ein .

— Paul Coulson
quelle

Unicode-Operatoren sind in Ordnung, wenn sie zur Darstellung tatsächlicher mathematischer Operatoren verwendet werden, schlecht, wenn sie in Codefragmenten verwendet werden, die sich zufällig in einem Kommentar befinden (z List<int>. B. ). Denken Sie beispielsweise daran, das Code-Snippet zu kopieren und einzufügen.

— Palec

Können Sie ein Beispiel dafür geben, wie dies in einem Kommentar verwendet wird? hat nie Unicode-Zeichen verwendet

— ClementWalter

1

Kopieren Sie das Zeichen und fügen Sie es wie oben beschrieben ein.

— Paul Coulson