C # XML Documentation Website Link


144

Czy w dokumentacji XML można zamieścić łącze do strony internetowej? Na przykład moja metoda jest podsumowana jako

///<Summary>
/// This is a math function I found HERE.
///</Summary>
public void SomeMathThing(Double[] doubleArray)
{
   ...
}

i kiedy piszę

SomeMathThing(

Chcę, aby technologia IntelliSense wyświetlała podsumowanie z opcją kliknięcia „TUTAJ” w celu wyświetlenia łącza do zewnętrznej witryny internetowej. czy to możliwe? Jak by to zrobiono?

Odpowiedzi:


149

Próbować:

///<Summary>
/// This is a math function I found <see href="http://stackoverflow.com">HERE</see>
///</Summary>

7
Obawiam się, że nie ma szczęścia. Nawet nie wyświetlało „TUTAJ”.
john

5
Hmmm, przepraszam. Zrobiłem trochę więcej badań (patrz tutaj i tutaj ) - i wygląda na to, że VS IDE nie wyświetli tych hiperłączy, ale narzędzie dokumentacji, takie jak SandCastle, będzie w stanie je wyświetlić.
dizzwave

2
Tak przy okazji, możesz przeczytać o Sandcastle tutaj . „Sandcastle, stworzone przez firmę Microsoft, jest darmowym narzędziem do tworzenia dokumentacji w stylu MSDN z zestawów .NET i powiązanych z nimi plików komentarzy XML. Jest oparte na wierszu poleceń i nie ma interfejsu GUI, funkcji zarządzania projektami ani automatycznego proces budowania ”. HTH!
dizzwave

1
Uwaga, istnieje pewna zmienność w obsłudze <see /> jako znacznika treści. Zauważyłem, że jest nieco bardziej spójny, gdy jest używany jako tag samozamykający, który wyświetla tylko surowy adres URL. (Co i tak jest lepszą dokumentacją: ponieważ „TUTAJ” nie dostarcza wiele wyjaśnień.)
gremlin

3
Działa to w VS 16.4.2. Nie jestem pewien, która wersja została dodana, tylko, że możesz teraz klikać łącza w oknie informacji o metodzie.
JB06

71

Trochę za późno na hype-train, ale oto, czego dowiedziałem się o Visual Studio 2015.

Moja próbka wygląda tak:

    /// <summary>
    ///     Retrieves information about the specified window. 
    ///     The function also retrieves the value at a specified offset into the extra window memory.
    ///     From <see cref="!:https://msdn.microsoft.com/en-us/library/windows/desktop/ms633585(v=vs.85).aspx">this</see> MSDN-Link.
    ///     AHref <a href="http://stackoverflow.com">here</a>.
    ///     see-href <see href="http://stackoverflow.com">here</see>.
    /// </summary>
    /// <param name="hwnd"></param>
    /// <param name="index"></param>
    /// <returns>
    ///     Testlink in return: <a href="http://stackoverflow.com">here</a>
    /// </returns>
    public static IntPtr GetWindowLongPtr(IntPtr hwnd, int index)
    {
        return IntPtr.Size == 4 ? GetWindowLongPtr32(hwnd, index) : GetWindowLongPtr64(hwnd, index);
    }

Wyniki są następujące:

  1. Etykietka:
    • Pokazuje cref-url z!:, Ale ukrywa „to”
    • Ukrywa ahref-url, ale wyświetla tekst
    • Ukrywa adres URL i tekst seehref Zrzut ekranu podpowiedzi Intellisense

  1. Przeglądarka obiektów:
    • Pokazuje cref-url z!:, Ale ukrywa „to” (nie można kliknąć)
    • Ukrywa ahref-url, ale wyświetla tekst (nie można go kliknąć)
    • Ukrywa adres URL i tekst seehref (nie można kliknąć) Zrzut ekranu programu ObjectBrowser

  1. ReSharper (CTRL + SHIFT + F1, polecenie ReSharper.ReSharper_QuickDoc)
    • Ukrywa cref-url z!:, Ale pokazuje „this” (nie można go kliknąć)
    • Czy teraz interpretuje ahref-url (wersja z 2016 i nowsze)
    • Ukrywa adres URL i tekst seehref (nie można kliknąć) Zrzut ekranu szybkiej pomocy Resharper

Wniosek: najlepszy, jak wskazał Heiner, byłby

See <a href="link">this link</a> for more information.

Aktualizacja Jak wskazał Thomas Hagström, Resharper obsługuje teraz klikalne adresy URL a-href. Zaktualizowano odpowiednio zrzut ekranu.


2
Właściwie dzięki ReSharper i CTRL + SHIFT + F1 adres URL jest klikalny, a link HTML jest kompatybilny, więc jest to rzeczywiście najlepsza opcja
Thomas Hagström

1
Dzięki Thomas Hagström, zaktualizowałem odpowiedź i zrzut ekranu.
MHolzmayr

26

Możesz użyć standardowej składni HTML:

<a href="http://stackoverflow.com">here</a>

Tekst zostanie wyświetlony w programie Visual Studio.


5
To jest najlepsze podejście. Ponieważ dane wyjściowe nadal będą miały sens w programie Visual Studio (po prostu pokazuje tekst), a łącze będzie działać w narzędziach dokumentacji, takich jak Sandcastle.
Snæbjørn

20

Możesz dołączyć przedrostek!: W krefie, aby przejść przez nietknięty w wygenerowanej dokumentacji XML, dzięki czemu narzędzia takie jak Dokument Innovasys! X i Sandcastle będą go używać. na przykład

/// <summary>
/// This is a math function I found <see cref="!:http://stackoverflow.com">HERE</see>
/// </summary>

Jednak program Visual Studio intellisense nie wyświetli tego jako łącza do funkcji Intellisense - nie byłoby to zbyt ważne, ponieważ jest to podpowiedź, więc i tak nie można jej kliknąć.


2
Byłby punkt, gdyby przeglądarka obiektów faktycznie w<see/> jakiś sposób utworzyła klikalne i rozpoznawane identyfikatory URI witryny (ponieważ przeglądarka obiektów nie jest etykietą narzędzia). Tylko mówię' ;-).
binki

6

Użyj tagu. Na przykład wykorzystałem to rozwiązanie w swoim projekcie

Wynik jest tutaj

Mój kod xml to:

/// <summary>
/// This is C# XML Documentation Website Link
/// <a href="/programming/6960426/c-sharp-xml-documentation-website-link">See more</a>
/// </summary>

Lub użyj tagu „zobacz”. Wynik jest taki sam, jak w przypadku tagu „a”

/// <summary>
/// This is C# XML Documentation Website Link
/// <see href="/programming/6960426/c-sharp-xml-documentation-website-link">See more</see>
/// </summary>
Korzystając z naszej strony potwierdzasz, że przeczytałeś(-aś) i rozumiesz nasze zasady używania plików cookie i zasady ochrony prywatności.
Licensed under cc by-sa 3.0 with attribution required.