Lien vers le site Web de documentation XML C #

144

Est-il possible d'inclure un lien vers un site Web dans la documentation XML? Par exemple, ma méthode est résumée comme

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

et quand je tape

SomeMathThing(

Je veux qu'IntelliSense affiche le résumé avec l'option de cliquer sur "ICI" pour créer un lien vers un site Web extérieur. Est-ce possible? Comment cela se ferait-il?

John
la source

Réponses:

149

Essayer:

///<Summary>
/// This is a math function I found <see href="http://stackoverflow.com">HERE</see>
///</Summary>
vertige
la source
7
Pas de chance, j'ai peur. Il n'a même pas affiché "ICI".
john
5
Hmmm, mes excuses. J'ai fait un peu plus de recherche (voir ici et ici ) - et il semble que VS IDE n'affiche pas ces hyperliens, mais un outil de documentation tel que SandCastle serait capable de les afficher.
dizzwave
2
Vous pouvez lire sur Sandcastle ici btw. "Sandcastle, créé par Microsoft, est un outil gratuit utilisé pour créer une documentation de type MSDN à partir d'assemblys .NET et de leurs fichiers de commentaires XML associés. Il est basé sur la ligne de commande et n'a pas d'interface graphique, de fonctionnalités de gestion de projet ou processus de construction. " HTH!
dizzwave
1
Notez qu'il existe une certaine variabilité dans la prise en charge de <see /> en tant que balise de contenu. Je l'ai trouvé un peu plus cohérent lorsqu'il est utilisé comme une balise auto-fermée affichant simplement l'URL brute. (Ce qui est de toute façon une meilleure documentation: comme "ICI" ne fournit pas beaucoup d'explications.)
gremlin
3
Cela fonctionne dans VS 16.4.2. Vous ne savez pas quelle version il a été ajouté, mais vous pouvez maintenant cliquer sur des liens dans la fenêtre d'informations sur la méthode.
JB06 le
71

Un peu en retard dans le train hype, mais voici ce que j'ai découvert pour Visual Studio 2015.

Mon échantillon ressemble à ceci:

    /// <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);
    }

Les résultats sont:

  1. Info-bulle:
    • Affiche cref-url avec!:, Mais masque "this"
    • Masque ahref-url mais affiche le texte
    • Masque l'URL et le texte de seehref Capture d'écran de l'info-bulle intellisense

  1. Navigateur d'objets:
    • Affiche cref-url avec!:, Mais masque "this" (non cliquable)
    • Masque ahref-url mais affiche le texte (non cliquable)
    • Masque l'URL et le texte de seehref (non cliquable) Capture d'écran d'ObjectBrowser

  1. ReSharper (CTRL + SHIFT + F1, commande ReSharper.ReSharper_QuickDoc)
    • Masque l'URL de la référence avec!:, Mais affiche "this" (non cliquable)
    • Interprète maintenant ahref-url (version de 2016 et plus récente)
    • Masque l'URL et le texte de seehref (non cliquable) Capture d'écran de Resharper QuickHelp

Conclusion: le meilleur, comme l'a souligné Heiner, serait

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

Mise à jour Comme l'a souligné Thomas Hagström, Resharper prend désormais en charge les URL cliquables a-href. Capture d'écran mise à jour en conséquence.

MHolzmayr
la source
2
En fait, avec ReSharper et CTRL + SHIFT + F1, une URL est cliquable et le lien HTML est compatible, c'est donc la meilleure option
Thomas Hagström
1
Merci Thomas Hagström, a mis à jour la réponse et la capture d'écran.
MHolzmayr
26

Vous pouvez utiliser la syntaxe HTML standard:

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

Le texte sera affiché dans Visual Studio.

Heiner
la source
5
C'est la meilleure approche. Comme la sortie aura toujours un sens dans Visual Studio (il ne montre que le texte) et le lien fonctionnera dans des outils de documentation comme Sandcastle.
Snæbjørn
20

Vous pouvez inclure un préfixe!: Dans un cref pour qu'il soit passé intact dans la documentation Xml générée afin que des outils tels que Innovasys Document! X et Sandcastle l'utiliseront. par exemple

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

Visual Studio intellisense ne l'affichera pas comme un lien pour intellisense - ne serait pas très utile car il s'agit d'une info-bulle, vous ne pouvez donc pas cliquer dessus de toute façon.

fubaar
la source
2
Il y aurait un point si Object Browser rendait les<see/> URI de site Web cliquables et reconnus d'une manière ou d'une autre (puisque Object Browser n'est pas une info-bulle). Juste en disant ;-).
binki
6

Utilisez une balise. Par exemple j'ai utilisé cette solution dans mon projet

Le résultat est ici

Mon code xml est:

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

Ou utilisez la balise "voir". Le résultat est le même de la balise "a"

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