如何自动修复 XML 注释警告

本文关键字：注释 警告 XML 何自动 | 更新日期: 2023-09-27 18:35:08

在我的 C# xml 注释中，我有很多这样的警告：

CS1574 XML 注释具有无法解析的 cref 属性"天"

其中使用了 <see> 元素而不是 <paramref> 。一个容易的错误。

/// <summary>
/// Add <see cref="days"/> days to <see cref="date"/>.
/// </summary>
public static double AddDays(double date, int days)
{
    return DateTime.FromOADate(date).AddDays(days).ToOADate();
}

我怎样才能全部修复它们？200 个文件中大约有 1000 个，所以我不想手动完成。查找和替换是行不通的，因为这至少会破坏<see>的合法使用。

新的 C# Roslyn 代码分析 API 会有所帮助吗？我可以想象代码可以找到这些警告，测试损坏的目标是否真的是参数的名称，如果是，则进行编辑以paramref.你觉得怎么样？

如何自动修复 XML 注释警告

您可以使用正则表达式执行查找和替换，该正则表达式仅在 see 标记中的 cref 与参数列表中的参数匹配时才匹配。

这是一个非常丑陋的正则表达式，应该可以工作：

((?:///'s*'<summary'>'s*'n)(?:'s*?///.*'n)*?'s*///.*?'<)see's+cref(?=(='"(:?.*)'"'s*/'>.*'n(?:///.*'n)*'s*///'s*'</summary'>['s'n]*.*'((?:[^')]|'n)*'3'b(?:[^')]|'n)*')['s'n]*'{))

然后使用此替换文本： 

$1paramref name

正则表达式启动捕获以获取要替换的文本之前的所有内容，然后查找摘要块的开头。 找到摘要块后，它会遍历摘要块行并查找see。如果它找到一个，它就会捕获see的cref。然后它开始向前看。它查找摘要块的末尾，然后查找可选的空白行，然后查找看起来有点像方法定义的标题的另外一行。（任何序列后跟括号参数列表，后跟 {） 在匹配的括号内，它从 see 标签（带有单词边界的 '3'b backref）中查找 cref。

如果匹配成功，替换文本将写出捕获的序言文本，然后将see cref切换到 paramref name 。 它不需要编写文本的其余部分，因为我们使用了一个前瞻组来匹配参数名称。

一些注意事项

  1. 您可能需要在同一源上运行多次
  2. 我的Visual Studio（2012）在捕获引用方面表现不佳替换文本，希望您的文本处理得更好。

总的来说，就像许多基于正则表达式的解决方案一样，您可以使用它来完成大部分工作，然后手动清理任何遗漏。

相关文章：