我正在尝试在我的备注中包含一个 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>
...
帮助我更好地记录我的代码。