StyleCop SA1650 在没有警告抑制的情况下将 URL 捕获为拼写错误的单词的解决方法

Question

我正在尝试在我的备注中包含一个 URL，如下例所示。这会导致 StyleCop 报告基于规则 SA1650（备注中拼写错误的单词）的警告，出于我们的目的，不能（通过策略）抑制该警告。这个警告并不奇怪，因为 URL 语法不需要正确的英文拼写。

...

/// <remarks>
/// <para>... some remarks ...</para>
/// <para>http://www.foo.wtvr.com</para>
/// <para>... some other remarks ...</para>
/// </remarks>

...

首先，在摘要/备注中包含 URL 是否被认为是不好的做法？我猜不是，因为 Visual Studio 可以识别链接并使它们可点击。如有必要，我会删除它，但我想将参考留给其他人。

如果这个不是被认为是不好的做法，有没有办法让 StyleCop 忽略 URL 文本 抑制警告（或添加整个 URL 或每个部分到公认的单词列表中）？我尝试了以下方法（URL 行上有四个正斜杠），但这会导致来自规则 SA1644 的警告（文档标题中不允许出现空行）：

...

/// <remarks>
/// <para>... some remarks ...</para>
//// <para>http://www.foo.wtvr.com</para>
/// <para>... some other remarks ...</para>
/// </remarks>

...

我目前的解决方案是使用comment-in-comment标签，如下所示，不会产生警告，但我不知道这是否是最佳实践：

...

/// <remarks>
/// <para>... some remarks ...</para>
/// <para><!--http://www.foo.wtvr.com--></para>
/// <para>... some other remarks ...</para>
/// </remarks>

...

帮助我更好地记录我的代码。

Answer 1

我相信在 cmets 中使用 http 链接是一种很好的做法。

使用

<see href="http://myurl.com/"/> 

在您的 cmets 中插入 URL 时，回答为 here。