原创文章,欢迎转载。转载请注明:关东升的博客
前面说到Swift注释的语法有两种:单行注释(//)和多行注释(/*...*/)。这里来介绍一下他们的使用规范。
1、文件注释
文件注释就在每一个文件开头添加注释,文件注释通常包括如下信息:版权信息、文件名、所在模块、作者信息、历史版本信息、文件内容和作用等。
下面看一个文件注释的示例:
/*
Copyright (C) 2015 Eorient Inc. All Rights Reserved.
See LICENSE.txt for this sample’s licensing information
Description:
This file contains the foundational subclass of NSOperation.
History:
15/7/22: Created by Tony Guan.
15/8/20: Add socket library
15/8/22: Add math library
*/
这个注释只是提供了版权信息、文件内容和历史版本信息等,文件注释要根据自己实际情况包括内容。
2、文档注释
文档注释就是这种注释内容能够生成API帮助文档。文档注释主要对类型、属性、方法或函数等功能。
文档注释是稍微将单行注释(//)和多行注释(/*...*/)做一点“手脚”后,就成为了文档注释,单行文档注释(///)和多行文档注释(/**...*/)。
下面代码示例:
import Foundation
/**
The protocol that types may implement if they wish to be
notified of significantoperation lifecycle events.
*/
protocol OperationObserver {
/// Invoked immediately prior to the `Operation`'s `execute()` method.
func operationDidStart(operation: Operation)
}
代码中使用了文档注释。
可以使用一些工具将这些文档注释生成API文件
3、代码注释
程序代码中处理文档注释还需要在一些关键的地方添加代码注释,文档注释一般是给一些看不到源代码的人看的帮助文档,而代码注释是给阅读源代码人参考的。代码注释一般是采用单行注释(//)和多行注释(/*...*/)。
有的时候也会在代码的尾端进行注释,这要求注释内容极短,应该在有足够的空白来分开代码和注释。尾端注释示例代码如下:
init(timeout: NSTimeInterval) {
self.timeout = timeout //初始化
}
4、使用地标注释
随着编码过程深入,工程代码量会增加,任何在这大量的代码中能快速找到需要方法或者是刚才修改过代码呢?
在Swift代码中使用地标注释,然后就可以使用Xcode工具在代码中快速查找了。地标注释有三个:
<!--[if !supportLists]-->l <!--[endif]-->MARK,用于方法或函数的注释。
<!--[if !supportLists]-->l <!--[endif]-->TODO,表示这里代码有没有完成,还要处理。
<!--[if !supportLists]-->l <!--[endif]-->FIXME,表示这里修改了代码。
这些注释会出现在Xcode的 Jump Bar中。来看一个示例:
class ViewController: UIViewController,
ÊUITableViewDataSource, UITableViewDelegate {
var listTeams: [[String:String]]!
override func viewDidLoad() {
super.viewDidLoad()
...
}
override func didReceiveMemoryWarning() {
super.didReceiveMemoryWarning()
//TODO: 释放资源 //使用TODO注释
}
// MARK: UITableViewDataSource 协议方法 //使用MARK注释
func tableView(tableView: UITableView,
ÊnumberOfRowsInSection section: Int) -> Int {
return self.listTeams.count
}
func tableView(tableView: UITableView,
ÊcellForRowAtIndexPath indexPath: NSIndexPath) -> UITableViewCell {
let cellIdentifier = "CellIdentifier"
let cell: UITableViewCell! = tableView
Ê.dequeueReusableCellWithIdentifier(cellIdentifier,
ÊforIndexPath: indexPath) as? UITableViewCell
// FIXME: 修改bug //使用了FIXME注释
let row = indexPath.row
let rowDict = self.listTeams[row] as [String:String]
...
return cell
}
// MARK: UITableViewDelegate 协议方法 //使用MARK注释
func tableView(tableView: UITableView,
ÊdidSelectRowAtIndexPath indexPath: NSIndexPath) {
...
}
}
上述代码中使用三种地标注释,在使用时候后面要跟有一个冒号(:)。
注释之后如果使用呢?打开Xcode的 Jump Bar,如下图,这些地标注释会在下拉列表中粗体显示,点击列表项就会跳转到注释行。
相关推荐
从零开始学swift,图灵原创,关东升著。基于swift2.x。2016年3月版
Swift学习笔记含项目代码.zipSwift学习笔记含项目代码.zipSwift学习笔记含项目代码.zipSwift学习笔记含项目代码.zipSwift学习笔记含项目代码.zipSwift学习笔记含项目代码.zipSwift学习笔记含项目代码.zipSwift学习...
以下是从零开始学习SwiftUI的一些建议: 了解Swift语言基础:SwiftUI是用Swift语言编写的,因此了解Swift语言的基础知识是非常重要的。你可以从苹果官方文档、在线教程或书籍中学习Swift语言。 学习SwiftUI基本概念...
最新的关于学习swift开发的书籍,讲的非常好
精选Swift相关的学习笔记与资料集合打包上传给大家,这里的笔记非常的容易看得懂,基本上学习编程的看这一堆东西就能很快上上手了,非常的实用。
swift 学习笔记 之 扩展
Swift学习的笔记,总结性的东西,很实用,非常适合新手看,之前学过OC的朋友基本上一看就能上手,非常的实用。
strings<——>csv 文件解析、转换
学习swift的笔记,自己记录的,必须50字,凑够了算,谢谢
swift 学习笔记 之 函数 编程题
ios开发 swift语言学习资料,入门学习,简单易懂;ios开发 swift语言学习资料,入门学习,简单易懂
swift学习控件篇:UITableview
swift学习控件篇:UICollectionView
IOS开发-Swift-基础知识学习笔记
贝塞尔曲线使用——模拟心跳曲线
NULL 博文链接:https://duchengjiu.iteye.com/blog/2184242
SwiftLint——Swift代码风格检查及自动格式化工具
Swift学习笔记 更新日志 学习资料 《The Swift Programming Language》中文版
学习swift的笔记,部分代码来自教程。打包的playground方便学习和查看效果。
Swift学习代码.zipSwift学习代码.zip