SketchK's Studio.

Swift Tips 003 - Referencing either external or internal parameter name when ...

字数统计: 492阅读时长: 1 min
2019/08/23 Share

每天了解一点不一样的 Swift 小知识

代码截图

01

代码出处: Swift Tips 003 by John Sundell

小笔记

今天截图里的关键点在哪里,怎么没看出来

注意两个 bar 的注释,一个注释里面的参数是 string,一个是 with

为什么 Swift 函数里面有 2 个 参数名(with 和 string)

在 Swift 官方文档中提到了每个函数都有一个 参数标签(argument label)以及一个参数名称(parameter name)

我们可以将参数标签理解为 external parameter,参数标签在调用函数的时候使用;调用的时候需要将函数的参数标签写在对应的参数前面。

我们可以将参数名称理解为 internal parameter,参数名称在函数的实现中使用。默认情况下,函数参数使用参数名称来作为它们的参数标签。

相关内容可以参考 函数 章节的内容

如何为 Swift 的 API 进行注释?

Apple 内部提供了一个名为 SourceKit 的私有框架来帮助开发者完成 Swift 的 API 注释,使用起来非常简单,在对应位置,使用 Command + Option + / 的组合键即可自动生成注释文档。

如果你实在无法忍受 SourceKit 的各种莫名问题,也可以尝试 Realm 团队提供的 API 注释工具 Jazzy

这个小 tips 有什么实际价值呢

试想一下在开发中,我们遇到下面的代码:

1
2
3
4
5
6
class Foo {
/**
* - parameter _: A string
*/
func bar(_ string: String,_ int: Int) {}
}

如果 Swift 的注释文档只支持参数标签,那么代码注释就会写成下面的样子:

1
2
- parameter _: A string
- parameter _: A Int

看到这样的注释,我想你内心肯定在说,这个 _ 标识符到底是什么鬼?这都谁跟谁啊?

但 Swift 提供了这个特性后,注释文档的书写变得更友好,也更灵活。

CATALOG
  1. 1. 代码截图
  2. 2. 小笔记
    1. 2.1. 今天截图里的关键点在哪里,怎么没看出来
    2. 2.2. 为什么 Swift 函数里面有 2 个 参数名(with 和 string)
    3. 2.3. 如何为 Swift 的 API 进行注释?
    4. 2.4. 这个小 tips 有什么实际价值呢