Xcode 中循环变量的文档注释

Question

我知道我们可以使用

/// index variable
var i = 0

作为单个变量的文档注释。

我们怎样才能对循环变量做同样的事情？

以下不起作用：

var array = [0]
/// index variable
for i in array.indices {
    // ...
}

或

var array = [0]
for /** index variable */ i in array.indices {
    // ...
}

---

背景：

我不使用“好”变量名的原因是我正在实现一个使用数学符号派生的数值算法。在这种情况下，它只有单字母变量名。为了更好地了解派生和实现之间的联系，我使用相同的变量名。

现在我想对代码中的变量进行注释。

Answer 1

/// 的使用主要用于在 Swift 中记录类、结构等的 API。

因此，如果在类/结构中的class、func、var/let 等之前使用，则您将文档附加到 Xcode 了解如何显示内联的代码方面。它不知道如何为函数内部的事物获取该信息，因为此时这不是 /// 的意图（它可能适用于简单的 var/let，但不太可能完全是故意的）。

改为使用简单的// 代码注释，以使任何在代码中工作的人受益，但避免过度记录代码，因为好的代码很可能会向精通该语言的任何人进行自我解释，并且可以添加不需要的文档只是阅读代码的方式。

这是目前 Swift 中代码文档的一个很好的参考 Swift Documentation

Answer 2

如果我在 PR 中看到这样的事情，我会强烈反对。 i 是循环索引广泛采用的“艺术术语”。一般来说，如果你的变量声明名需要​​注释，你需要一个更好的变量名。有一些例外，例如当它存储具有复杂用途/不变量的数据时，这些数据无法在类型系统中以更好的方式捕获。

我认为评论是初学者犯错误的一个领域，主要是被老师误导或尚未完全理解 cmets 的目的。不存在用于创建基于英语的伪编程语言的注释，您的整个应用程序都将在其中复制。理解编程语言是项目贡献者的最低期望。绝对没有 cmets 应该解释编程语言的特性。例如。 var x: Int = 0 // declares a new mutable variable called x, to the Int value 0，Swift 学习教程除外。

以这种方式发表评论似乎很有帮助，因为您可能会争辩说它为初学者解释了一些事情。可能是这样，但对于所有其他读者来说，这令人窒息。想象一下，如果小说必须定义他们使用的所有英文单词。

相反，文档的目的是解释事物的用途和用途。回答如下问题：

• 您为什么以这种方式实现某些东西，而不是另一种方式？
• 这种方法有什么用途？
• 什么时候调用我的委托的这个方法？

案例研究：Equatable

举个例子，看看documentation of Equatable

注意事项：

1. 它是为 Swift 开发人员的受众编写的。它使用了许多它没有解释的东西，例如数组、字符串、常量、变量声明、赋值、if 语句、方法调用（例如Array.contains(_:)）、字符串插值、print 函数。李>
2. 它解释了该协议的一般用途。
3. 它解释了如何使用这个协议
4. 它解释了如何将此协议用于自己的用途

5. 它记录了类型系统无法强制执行的合同要求。

   由于 Equatable 类型实例之间的相等性是一种等价关系，因此任何符合 Equatable 的自定义类型都必须满足三个条件，对于任何值 a、b 和 c：

   • a == a 始终为真（自反性）
   • a == b 暗示 b == a（对称）
   • a == b 和 b == c 暗示 a == c（传递性）

6. 它解释了对协议可能存在的误解（“平等与身份分离”）