Jak mieć komentarze w IntelliSense dla funkcji w programie Visual Studio?

W programie Visual Studio i C # podczas korzystania z funkcji wbudowanej, takiej jak ToString (), funkcja IntelliSense wyświetla żółte pole wyjaśniające, co robi.

Jak mogę to mieć dla funkcji i właściwości, które piszę?

Aby wygenerować obszar, w którym możesz określić opis funkcji i każdy parametr funkcji, wpisz w wierszu przed funkcją i naciśnij Enter:

• DO#: ///

• VB: '''

Zobacz zalecane tagi dla komentarzy do dokumentacji (przewodnik programowania C #), aby uzyskać więcej informacji na temat zawartości strukturalnej, którą można uwzględnić w tych komentarzach.

Potrzebujesz komentarzy XML - w zasadzie są one zgodne z następującą składnią (jak niejasno opisał Solmead):

DO#

///<summary>
///This is a description of my function.
///</summary>
string myFunction() {
     return "blah";
}

VB

'''<summary>
'''This is a description of my function.
'''</summary>
Function myFunction() As String
    Return "blah"
End Function

<c>text</c>- tekst, który chcesz oznaczyć jako kod.
Znacznik < c > umożliwia wskazanie, że tekst w opisie powinien być oznaczony jako kod. Użyj < kod >, aby wskazać wiele wierszy jako kod.

<code>content</code>- tekst, który chcesz oznaczyć jako kod. Tag
< code > umożliwia wskazanie wielu wierszy jako kodu. Użyj < c >, aby wskazać, że tekst w opisie powinien być oznaczony jako kod.

<example>description</example>- Opis przykładowego kodu.
Znacznik < example > pozwala określić przykład użycia metody lub innego członka biblioteki. Zwykle wiąże się to z użyciem tagu < code >.

<exception cref="member">description</exception>- opis wyjątku. Tag
< ception > pozwala określić, które wyjątki mogą być generowane. Ten tag można zastosować do definicji metod, właściwości, zdarzeń i indeksatorów.

<include file='filename' path='tagpath[@name="id"]' />
Znacznik < include > umożliwia odwoływanie się do komentarzy w innym pliku, które opisują typy i składowe w kodzie źródłowym. Jest to alternatywa dla umieszczania komentarzy dokumentacji bezpośrednio w pliku kodu źródłowego. Umieszczając dokumentację w osobnym pliku, możesz zastosować kontrolę źródła do dokumentacji niezależnie od kodu źródłowego. Jedna osoba może wyewidencjonować plik kodu źródłowego, a ktoś inny może wyewidencjonować plik dokumentacji. Znacznik < include > używa składni XML XPath. Zapoznaj się z dokumentacją XPath, aby dowiedzieć się, jak dostosować użycie < include >.

<list type="bullet" | "number" | "table">
    <listheader>
        <term>term</term>
        <description>description</description>
    </listheader>
    <item>
        <term>term</term>
        <description>description</description>
    </item>
</list>

Blok < listheader > służy do definiowania wiersza nagłówka tabeli lub listy definicji. Definiując tabelę, wystarczy podać w nagłówku wpis dotyczący terminu. Każda pozycja na liście jest określona za pomocą bloku < item >. Tworząc listę definicji, musisz określić zarówno termin, jak i opis. Jednak w przypadku tabeli, listy punktowanej lub listy numerowanej wystarczy podać wpis do opisu. Lista lub tabela może mieć dowolną liczbę bloków < item >.

<para>content</para>
Znacznik < para > jest używany wewnątrz znacznika, takiego jak < summary >, < uwagi > lub < Returns >, i umożliwia dodawanie struktury do tekstu.

<param name="name">description</param>
Znacznik < param > powinien być użyty w komentarzu do deklaracji metody, aby opisać jeden z parametrów metody. Aby udokumentować wiele parametrów, użyj wielu tagów < param >.
Tekst znacznika < param > zostanie wyświetlony w technologii IntelliSense, przeglądarce obiektów oraz w raporcie sieci Web z komentarzem do kodu.

<paramref name="name"/>
Znacznik < paramref > umożliwia wskazanie, że słowo w komentarzu w kodzie, na przykład w bloku < summary > lub < remarks >, odnosi się do parametru. Plik XML można przetworzyć w celu sformatowania tego słowa w inny sposób, na przykład czcionką pogrubioną lub kursywą.

< permission cref="member">description</permission>
Znacznik < zgoda > tag pozwala udokumentować dostęp członka. Klasa PermissionSet umożliwia określenie dostępu do elementu członkowskiego.

<remarks>description</remarks>
Znacznik < uwagi > służy do dodawania informacji o typie, uzupełniając informacje określone przez < podsumowanie >. Te informacje są wyświetlane w przeglądarce obiektów.

<returns>description</returns>
W komentarzu do deklaracji metody należy użyć znacznika < Returns > opisującego zwracaną wartość.

<see cref="member"/>
Znacznik < see > umożliwia określenie łącza w tekście. Użyj < seealso >, aby wskazać, że tekst powinien zostać umieszczony w sekcji Zobacz też. Użyj atrybutu cref, aby utworzyć wewnętrzne hiperłącza do stron dokumentacji dla elementów kodu.

<seealso cref="member"/>
Znacznik < seealso > umożliwia określenie tekstu, który może się pojawić w sekcji Zobacz też. Użyj < zobacz >, aby określić łącze z tekstu.

<summary>description</summary>
Znacznik < summary > powinien być używany do opisu typu lub elementu członkowskiego typu. Użyj < uwagi >, aby dodać dodatkowe informacje do opisu typu. Użyj atrybutu cref, aby włączyć narzędzia dokumentacji, takie jak Sandcastle, do tworzenia wewnętrznych hiperłączy do stron dokumentacji dla elementów kodu. Tekst tagu < summary > jest jedynym źródłem informacji o typie w technologii IntelliSense i jest również wyświetlany w przeglądarce obiektów.

<typeparam name="name">description</typeparam>
Znacznik < typeparam > powinien być używany w komentarzu dla deklaracji typu ogólnego lub metody w celu opisania parametru typu. Dodaj tag dla każdego parametru typu ogólnego typu lub metody. Tekst tagu < typeparam > zostanie wyświetlony w IntelliSense, raporcie sieci Web z komentarzami do kodu przeglądarki obiektów.

<typeparamref name="name"/>
Użyj tego znacznika, aby umożliwić użytkownikom pliku dokumentacji sformatowanie słowa w inny sposób, na przykład kursywą.

<value>property-description</value>
Znacznik < value > umożliwia opisanie wartości, którą reprezentuje właściwość. Należy zwrócić uwagę, że po dodaniu właściwości za pomocą kreatora kodu w środowisku programistycznym Visual Studio .NET zostanie dodany tag < summary > dla nowej właściwości. Następnie należy ręcznie dodać tag < value >, aby opisać wartość, którą reprezentuje właściwość.

Wykonuj komentarze XML, w ten sposób

/// <summary>
/// This does something that is awesome
/// </summary>
public void doesSomethingAwesome() {}

użyj ///, aby rozpocząć każdy wiersz komentarza i niech komentarz zawiera odpowiedni xml dla czytnika metadanych.

///<summary>
/// this method says hello
///</summary>
public void SayHello();

Chociaż osobiście uważam, że te komentarze są zwykle błędne, chyba że tworzysz klasy, w których kod nie może być odczytany przez konsumentów.

Nazywa się to komentarzami XML . Są częścią Visual Studio od zawsze.

Możesz ułatwić sobie proces tworzenia dokumentacji, korzystając z GhostDoc , bezpłatnego dodatku do programu Visual Studio, który generuje komentarze w formacie XML-doc. Po prostu umieść kursor na metodzie / właściwości, którą chcesz udokumentować, i naciśnij Ctrl-Shift-D.

Oto przykład z jednego z moich postów .

Mam nadzieję, że to pomoże :)

W CSharp, jeśli utworzysz zarys metody / funkcji z jej parametrami, to po dodaniu trzech ukośników automatycznie wygeneruje sekcję podsumowania i parmów.

Więc wstawiłem:

public string myMethod(string sImput1, int iInput2)
{
}

Następnie umieściłem trzy /// przed nim, a program Visual Studio dał mi to:

/// <summary>
/// 
/// </summary>
/// <param name="sImput1"></param>
/// <param name="iInput2"></param>
/// <returns></returns>
public string myMethod(string sImput1, int iInput2)
{
}

Zdefiniuj takie metody, a uzyskasz potrzebną pomoc.

    /// <summary>
    /// Adds two numbers and returns the result
    /// </summary>
    /// <param name="first">first number to add</param>
    /// <param name="second">second number to </param>
    /// <returns></returns>
    private int Add(int first, int second)
    {
        return first + second;
    }

Zrzut ekranu użycia kodu

przeczytaj http://msdn.microsoft.com/en-us/library/3260k4x7.aspx Samo określenie komentarzy nie spowoduje wyświetlenia komentarzy pomocy w programie Intellisense.

Wszystkie te inne odpowiedzi mają sens, ale są niekompletne. Program Visual Studio będzie przetwarzać komentarze XML, ale musisz je włączyć. Oto jak to zrobić:

Intellisense użyje komentarzy XML wprowadzonych w kodzie źródłowym, ale musisz je włączyć za pomocą opcji programu Visual Studio. Idź do Tools> Options> Text Editor. W przypadku Visual Basic Włącz ustawienie Advanced> Generate XML documentation comments for '''. W przypadku C # włącz ustawienie Advanced> Generate XML documentation comments for ///. Intellisense użyje komentarzy podsumowujących po wprowadzeniu. Będą dostępne z innych projektów po skompilowaniu przywoływanego projektu.

Aby utworzyć zewnętrzną dokumentacją, trzeba wygenerować plik XML przez Project Settings> Build> XML documentation file:ścieżki, który kontroluje kompilator /docopcji. Będziesz potrzebować zewnętrznego narzędzia, które pobierze plik XML jako dane wejściowe i wygeneruje dokumentację w wybranym przez Ciebie formacie wyjściowym.

Należy pamiętać, że wygenerowanie pliku XML może znacznie wydłużyć czas kompilacji.

Również dokument-duch dodatku do programu Visual Studio spróbuje utworzyć i wypełnić komentarze nagłówka na podstawie nazwy funkcji.

Solmead ma poprawną odpowiedź. Aby uzyskać więcej informacji, zobacz Komentarze XML .