5

我正在尝试在我的备注中包含一个 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>

...

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

4

1 回答 1

9

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

利用

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

在您的评论中插入 URL 时,如在此处回答。

于 2016-04-16T21:14:03.803 回答