C# XML 文档网站链接

Posted 2023-03-25

【中文标题】C# XML 文档网站链接

【英文标题】：C# XML Documentation Website Link

【发布时间】：2011-10-21 02:03:00

【问题描述】：

是否可以在 XML 文档中包含指向网站的链接？例如，我的方法总结为

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

   ...

当我输入时

SomeMathThing(

我希望 IntelliSense 显示摘要，并带有单击“此处”以链接到外部网站的选项。这可能吗？怎么做？

【问题讨论】：

这是由 GitHub 上的 Roslyn 问题实现的：<see> tags in XML docs should be clickable links in the IntelliSense popups.

【参考方案1】：

试试：

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

【讨论】：

恐怕运气不好。它甚至没有显示“这里”。

嗯，很抱歉。我做了更多的研究（见here和here）——看起来VS IDE不会显示这些超链接，但是像SandCastle这样的文档工具可以显示它们。

您可以阅读有关 Sandcastle here btw 的信息。 “由 Microsoft 创建的 Sandcastle 是一个免费工具，用于从 .NET 程序集及其关联的 XML 注释文件创建 MSDN 样式的文档。它基于命令行，没有 GUI 前端、项目管理功能或自动化构建过程。” HTH！

这适用于 VS 16.4.2。不确定添加了什么版本，只是您现在可以单击方法信息窗口中的链接。

适用于 VS 2019，确切的版本号是 VS 16.6.4。首先我尝试使用“cref”，但“href”渲染得很好。一个技巧是，当工具提示悬停时，将鼠标指针移到工具提示之外，您也可以单击链接导航到 url。好东西VS！它也适用于 Vs Code 吗？嗯嗯..

【参考方案2】：

炒作有点晚了，但这是我在 Visual Studio 2015 中发现的。

我的示例如下所示：

    /// <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://***.com">here</a>.
    ///     see-href <see href="http://***.com">here</see>.
    /// </summary>
    /// <param name="hwnd"></param>
    /// <param name="index"></param>
    /// <returns>
    ///     Testlink in return: <a href="http://***.com">here</a>
    /// </returns>
    public static IntPtr GetWindowLongPtr(IntPtr hwnd, int index)
    
        return IntPtr.Size == 4 ? GetWindowLongPtr32(hwnd, index) : GetWindowLongPtr64(hwnd, index);
    

结果是：

工具提示： 用 !: 显示 cref-url，但隐藏“this” 隐藏 ahref-url 但显示文本 隐藏seehref url和文本

---

对象浏览器： 用 !: 显示 cref-url，但隐藏“this”（不可点击） 隐藏 ahref-url 但显示文本（不可点击） 隐藏 seehref url 和文本（不可点击）

---

ReSharper（CTRL+SHIFT+F1，命令 ReSharper.ReSharper_QuickDoc） 用 !: 隐藏 cref-url，但显示“this”（不可点击） 现在可以解释 ahref-url（2016 年及更新的版本） 隐藏 seehref url 和文本（不可点击）

结论：正如 Heiner 指出的，最好的应该是

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

更新 正如 Thomas Hagström 所指出的，Resharper 现在支持可点击的 a-href URL。相应地更新了屏幕截图。

【讨论】：

实际上，使用 ReSharper 和 CTRL+SHIFT+F1 可以点击 url 并且兼容 html 链接，所以这确实是最好的选择

感谢 Thomas Hagström，更新了答案和截图。

【参考方案3】：

您可以使用标准的 HTML 语法：

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

文本将显示在 Visual Studio 中。

【讨论】：

这是最好的方法。因为输出在 Visual Studio 中仍然有意义（它只显示文本），并且链接将在 Sandcastle 等文档工具中工作。

【参考方案4】：

您可以在 cref 中包含 !: 前缀，使其在生成的 Xml 文档中原封不动地通过，以便 Innovasys Document! X 和 Sandcastle 等工具使用它。例如

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

Visual Studio intellisense 不会将其显示为 intellisense 的链接 - 没有多大意义，因为它是一个工具提示，因此您无论如何都无法单击它。

【讨论】：

如果Object Browser actually made <see/> clickable和以某种方式识别网站 URI，那将是有意义的（因为对象浏览器不是工具提示）。只是说';-)。

这种方法现在已经过时了；它会产生代码分析警告CA1200: Avoid using cref tags with a prefix。首选锚标记 ()。

【参考方案5】：

使用<a> 标签。例如，我在我的项目中使用了这个解决方案：

结果：

我的 XML 代码：

/// <summary>
/// This is C# XML Documentation Website Link
/// <a href="https://***.com/questions/6960426/c-sharp-xml-documentation-website-link">See more</a>
/// </summary>

或使用<see> 标签。结果与<a>标签相同。

/// <summary>
/// This is C# XML Documentation Website Link
/// <see href="https://***.com/questions/6960426/c-sharp-xml-documentation-website-link">See more</see>
/// </summary>

【参考方案6】：

我也尝试过<see href="https://some.com/>，但没有成功；然而，我随后尝试了<seealso href="https://some.url/">，它确实工作了。