Jak zmienić znaczenie znaków w komentarzach C #?

112

Zrozumiałem dzisiaj, że nie wiem, jak uciec ze znaków w komentarzach dla C #. Chcę udokumentować ogólną klasę C #, ale nie mogę napisać właściwego przykładu, ponieważ nie wiem, jak uciec przed znakami <i >. Czy muszę używać <i >? Nie podoba mi się, że tak jest, ponieważ chcę ułatwić czytanie komentarza w rzeczywistym dokumencie, więc nie muszę generować jakiegoś dokumentu z kodem, aby móc odczytać przykładowy kod.

c#

— Tomas Jansson
źródło

1

Czy mógłbyś pokazać przykładowy komentarz?

— BoltClock

możliwy duplikat ciągu Xml w komentarzu podsumowującym C #

— Mark Pim

1

@Mark: Masz rację, ale to nie tylko XML ... Próbowałem napisać przykład dla typów generycznych, który nie jest XML, ale używa '<' i '>'. Ale rozwiązanie jest takie samo dla obu.

— Tomas Jansson

Biorąc pod uwagę popularność szablonów w językach C ++, Java, C # ... jaką wymówkę ma Microsoft, by używać niedopracowanych ograniczników XML? Zwykły brak jasności i przewidywania.

— Rick O'Shea

141

Jeśli chcesz <zmienić znaczenie znaków w komentarzach XML, musisz użyć encji znakowych, więc należy je zmienić tak <, jak w pytaniu.

Alternatywą dla ucieczki jest użycie CDATAsekcji w tym samym celu.

Jak zauważyłeś, dałoby to dobrze wyglądającą dokumentację, ale okropny komentarz do przeczytania ...

— Oded
źródło

19

Tylko w celach informacyjnych <byłoby <i >będzie >. Na przykładList<string> myStringList = new List<string>();

— Arvo Bowen,

@ArvoBowen Na wypadek, gdyby ktoś nie zauważył oczywistego, lt/ gtoznacza odpowiednio „mniej niż” / „większe niż”.

— Lukas Juhrich

1

Co ciekawe, tylko <musi się uciec z <, >mogą zatrzymać się, jak to jest: List<string> myStringList = new List<string>();. Przynajmniej to działa w inteligencji. O dziwo, CDATA nie działa w inteligencji. Nie sprawdziłem, jak to wygląda w dokumentach generowanych automatycznie.

— Peter Huber

Potwierdza, że VS 2013 nie renderuje się CDATAw trybie Intellisense. <sprawia, że komentarz jest trudny do odczytania.

— Alex

52

W zwykłych komentarzach C # można użyć dowolnego znaku (z wyjątkiem sytuacji, */gdy komentarz rozpoczął się od /*lub znaku nowego wiersza, jeśli komentarz rozpoczął się od //). Jeśli używasz komentarzy XML, możesz użyć sekcji CDATA, aby dołączyć znaki „<” i „>”.

Zobacz ten artykuł na blogu MSDN, aby uzyskać więcej informacji na temat komentarzy XML w języku C #.

Na przykład

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

— Mark Pim
źródło

12

Prawdopodobnie masz rację, jeśli chcesz generować ładnie wyglądające dokumenty html, ale bardziej interesuje mnie uzyskiwanie poprawnych wskazówek dotyczących inteligencji w VS, a do tego wydaje się, że muszę używać ucieczki XML. Ale +1 za alternatywę.

— Tomas Jansson

2

Hmm, nieczytelne śmieci maszynowe w moich komentarzach pomagają tylko wtedy, gdy poświęcimy czas na zbudowanie naszego pliku dokumentu, gdy ogromna, ogromna, ogromna (czy wspomniałem ogromną?) Większość przypadków użycia to czytanie komentarzy w źródle (najlepiej w interfejsie) .

— Rick O'Shea

19

Powiedziałeś: „Chcę ułatwić czytanie komentarza w samym dokumencie”. Zgadzam się.

Deweloperzy spędzają większość swojego życia w kodzie , nie przeglądając automatycznie generowanych dokumentów. Są świetne dla bibliotek innych firm, takich jak wykresy, ale nie do rozwoju wewnętrznego, w którym pracujemy z całym kodem. Jestem trochę zszokowany, że MSFT nie wymyśliło tutaj rozwiązania, które lepiej wspierałoby programistów. Mamy regiony, które dynamicznie rozwijają / zwijają kod ... dlaczego nie możemy mieć przełącznika renderowania komentarzy w miejscu (między nieprzetworzonym tekstem a przetworzonym komentarzem XML lub między nieprzetworzonym tekstem a przetworzonym komentarzem HTML)? Wydaje się, że powinienem mieć pewne podstawowe możliwości HTML w komentarzach do mojej metody / klasy w prologu (czerwony tekst, kursywa, itp.). Z pewnością IDE mogłoby trochę magii przetwarzania HTML, aby ożywić komentarze w tekście.

Moje rozwiązanie typu hack-of-a-solution : zmieniam „<” na „{” i „>” na „}”. To wydaje się obejmować typowy przykładowy komentarz dotyczący stylu użycia, w tym Twój konkretny przykład. Niedoskonały, ale pragmatyczny biorąc pod uwagę problem z czytelnością (i problemy z kolorowaniem komentarzy IDE, które pojawiają się podczas używania znaku „<”)

— Dave
źródło

5

Twoja „hack of a solution” wydaje się być bardziej poprawna niż myślisz. Zgodnie z tym kompilator rozpoznaje nawiasy klamrowe jako nawiasy kątowe i odpowiednio je wiąże .

— RubberDuck,

8

Komentarze XML w języku C # są zapisywane w języku XML, więc należy użyć zwykłych znaków ucieczki XML.

Na przykład...

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

— Bob Black
źródło

5

Znalazłem znośne rozwiązanie tego problemu, po prostu dołączając dwa przykłady: jedną trudną do odczytania wersję w komentarzach XML ze znakami ucieczki i inną czytelną wersję wykorzystującą konwencjonalne //komentarze.

Proste ale efektywne.

— HolySamosa
źródło

0

Lepszym niż użycie {...} jest użycie ≤ ... ≥ (znak mniejszy lub równości, znak równości lub większy, U2264 i U2265 w Unicode). Wygląda jak podkreślone nawiasy kątowe, ale nadal zdecydowanie nawiasy kątowe! I dodaje tylko kilka bajtów do twojego pliku kodu.

— Mick Bruno
źródło

0

Jeszcze lepiej wypróbuj U2280 i U2281 - po prostu skopiuj i wklej z listy znaków Unicode (sekcja operatorów matematycznych).

— Paul Coulson
źródło

Operatory Unicode są OK, gdy są używane do reprezentowania rzeczywistych operatorów matematycznych, słabe, jeśli są używane we fragmentach kodu, które znajdują się w komentarzu (np List<int>.). Pomyśl np. O skopiowaniu i wklejeniu fragmentu kodu.

— Palec

czy możesz podać przykład wykorzystania tego w komentarzu? w rzeczywistości nigdy nie używał znaków Unicode

— ClementWalter

1

Skopiuj i wklej znak, jak opisano powyżej.

— Paul Coulson,