2016-06-07 12 views
5

Czy istnieje sposób użycia pogrubienia lub kursywa wewnątrz komentarzy do dokumentacji? Coś jak:Pogrubienie lub kursywą w komentarzach dokumentacji C# lub VB?

/// <summary>Cleanup method. This is <b>recommended</b> way of cleanup.</summary> 
public void CleanAll(); 

List of predefined tags nie zawiera takiej możliwości, ale wiesz o jakiś sposób osiągnięcia nacisk/podkreślając? Najlepiej, gdyby można go było pokazać również w etykietkach narzędzi po najechaniu kursorem na kod.

Mamy tam <c> i <code>, ale już mają swoją semantykę.

+4

nie jego komentarze trzeba się zastanawiać - wszelkie ważne XML jest dopuszczalna w nich - co jest jej analizowania wynikowy XML trzeba się zastanawiać, że to, co pozwoli trochę znaczników formatowania. – Jamiec

Odpowiedz

9

Nie ściśle, nie. Jednakże, Sandcastle (generator dokumentacji, który generuje HTML z dokumentacji) obsługuje tylko użycie HTML tam, więc możesz użyć <em> i <strong> dobrze jeśli zbudujesz go z Sandcastle.

Innymi słowy: jak już zauważyli Jamiec, komentarze do dokumentacji XML są po prostu XML. Możesz tam umieścić dowolny poprawny XML; kompilator z radością napisze to do pliku XML dokumentacji. Wszystko zależy od oprogramowania, które przetwarza ten plik. Sandcastle po prostu przekazuje wszystko, o czym nie wie, jak HTML, ponieważ to jest jego format wyjściowy.

Visual Studio będzie po prostu zignorować je podczas wyświetlania podpowiedzi pomocy:

ReSharper w swojej Ctrl + Q widzenia pokaże znaczniki HTML jako tekst, który sprawia, że ​​rzeczy nieco brzydkie:

Zwykle dotyczą one Ciebie tylko jeśli u tworzymy bibliotekę, z której mogą korzystać inni. Ale oznacza to również, że w IDE nikt nie może zobaczyć twojego nacisku zgodnie z przeznaczeniem.

Znalazłem niewielką potrzebę podkreślenia podczas pisania dokumentacji API; często możesz napisać zdanie inaczej lub zrestrukturyzować, aby mieć ważne węzły w osobnym akapicie pod koniec, aby w ogóle nie wymagać naciskania. Spójny język i frazowanie pomaga również czytelnikom w zbieraniu ważnych notatek, gdy już się do tego przyzwyczają.

Twój kod prawdopodobnie był tylko przykładem, ale myślę, że podsumowanie podsumowanie wymaga podkreślenia, jako że tylko zauważa - w krótkim zdaniu - czym jest typ lub metoda. Jeśli cokolwiek, używaj go w uwagach, a nawet wtedy dokładnie się zastanowię, czy naprawdę tego potrzebujesz.

+0

Następnie nadal trzeba uciec, ponieważ powinna to być poprawna zawartość XML. –

+3

@PatrickHofman: Jestem całkiem pewien, że '

Niektóre pogrubienie tekst' _jest_ poprawny XML. Nie ma potrzeby ucieczki. – Joey

+2

Przepraszam, masz rację. Właśnie myślałem o użyciu '<' w komentarzach, co nie jest dozwolone. Tych trzeba uciec, a te prawdopodobnie też skończyć poprawnie. –

1

Alternatywnym sposobem jest użycie stylu znacznika wiki typu wiki.

/// <summary>Cleanup method. This is *recommended* way of cleanup.</summary> 
public void CleanAll(); 
+0

Czy nie są potrzebne żadne wtyczki? Czy było to już możliwe w Visual Studio 2015? – miroxlav