Swift注释风格

Swift注释风格,第1张

概述前言 良好的注释,有助于开发和维护,请正视注释!在Swift2.0之前与之后是不一样的,这里是基于Swift2.0的。 看看ObjectiveC中常用的注释 看看下面是笔者对UIActionSheet封装的一个通用方法的注释: /** * @author huangyibiao * * Block版本的actionSheet,具体如何使用请参考UIActionSheet * * @param in 前言

良好的注释,有助于开发和维护,请正视注释!在Swift2.0之前与之后是不一样的,这里是基于Swift2.0的。

看看ObjectiveC中常用的注释

看看下面是笔者对UIActionSheet封装的一个通用方法的注释:

/** * @author huangyibiao * * Block版本的actionSheet,具体如何使用请参考UIActionSheet * * @param inVIEw 父视图 * @param Title 标题 * @param cancelTitle 取消按钮标题 * @param destructiveTitle destructive按钮标题 * @param otherTitles 其它按钮的标题 * @param callback 按钮点击的回调 * * @note 最多支持30项 * @see UIActionSheet * @see HDFActionSheetClickedbuttonBlock * * @return 所呈现的UIActionSheet视图 */+ (UIActionSheet *)hdf_showInVIEw:(UIVIEw *)inVIEw                           Title:(Nsstring *)Title                     cancelTitle:(Nsstring *)cancelTitle                destructiveTitle:(Nsstring *)destructiveTitle                     otherTitles:(NSArray *)otherTitles                        callback:(HDFActionSheetClickedbuttonBlock)callback;

上面只是一个API的注释例子,让我们分析:

API功能性描述:可以使用@brIEf标识,也可以省略 参数说明:使用@param 参数名称 参数功能描述 作者说明:使用@author 作者名称 特别说明:使用@note 注意事项说明 参考说明:使用@see 类型名称 返回值: 使用@return 返回值说明
这是比较标准的写法了。 在Swift2.0中的注释方式

在swift中就不推荐使用/**/的方式来注释API头了,因为我们发现输入/**/时,不会自动对齐了,这就显得难看了。更多地,我们会使用///来注释。

/// Get the url of category of technology////// - parameter currentPage: Current page index/// - parameter pageSize: How many rows to load////// - returns: The absolute urlstatic func technologyUrl(currentPage: Int,pageSize: Int) ->String {  let url = @H_403_93@"ArticleServer/queryArticleListBycategory/2"  return baseUrl + @H_403_93@"\(url)/\(currentPage)/\(pageSize)"}

由此简单的API注释可以看出来:

注释使用///的方式来添加,苹果的API都使用了这种方式
API功能性描述,直接添加说明即可 参数说明:使用 - parameter 参数名: 参数功能说明 返回值说明:使用 - returns: 返回说明

当然,我们仍然可以使用/** */的方式,只是与苹果的方式保持一致,我相信会更好一些。事实上并不只是这些,在Swift中注释是支持markdown语法的,因此只要您会Markdown语法,就可以添加超链接,图片,gif图片等。看看下面一张截图:

这是一张gif图,是可以看到动画的哦。

在参数中添加图片,只需要遵守Markdown语法即可轻松添加:![image](图片链接),这是固定的格式。
在参数中添加链接,只需要[显示的名称](超链接)
这是不是很强大呢?当组件化时,只需要将图片放在注释中,外部开发人员只需要按下option+鼠标点击就可以看到效果了,比千言万语要容易懂。

注意:对于一个API头会采用上面的注释方式,但是在API内部,我们仍然会使用//或者/**/来注释某一行。对于代码块注释,我们也可以采用Markdown方式来注释,添加图片,链接等。

自动生成注释插件

作为开发人员,怎么能不使用Xcode的插件呢,这有助于我们飞得更快。
在这之前,我们先安装一个插件管理器,在终端输入:

curl -fsSL https://raw.githubusercontent.com/supermarin/Alcatraz/deploy/Scripts/install.sh | sh

安装完成后,就可以搜索VVdocument安装。

看下图,重启Xcode后,在Xcode的菜单栏window中有一个Package Manager,点击就可以打开Alcatraz的界面,在搜索框中输入VVdocument就可以搜索出来了,然后点击Install即可,安装后需要重装启动Xcode。如下图:

重启Xcode后,在Window中有一个叫VVdocument的,点击它,就会显示如下界面,在这里就可以设置触发方式等,如下图:

上图为本人的设置界面,个人习惯以输入///来触发自动生成注释。

原文来自笔者专属博客:阅读原文 关注我

微信公众号:iOSDevShares
有问必答QQ群:324400294

总结

以上是内存溢出为你收集整理的Swift注释风格全部内容,希望文章能够帮你解决Swift注释风格所遇到的程序开发问题。

如果觉得内存溢出网站内容还不错,欢迎将内存溢出网站推荐给程序员好友。

欢迎分享,转载请注明来源:内存溢出

原文地址: http://outofmemory.cn/web/1081792.html

(0)
打赏 微信扫一扫 微信扫一扫 支付宝扫一扫 支付宝扫一扫
上一篇 2022-05-27
下一篇 2022-05-27

发表评论

登录后才能评论

评论列表(0条)

保存