Swift 注释和文档

news2024/11/15 4:32:27

今天,我知道我写是什么,上帝和我知道

明天,我知道这个代码什么意思,

后天,我知道这是我写的代码,

一周后,这TM谁写的代码,此时只有上帝才知道啥意思

论代码注释的重要性。

普通注释

普通注释主要为了提示编码和阅读者,逻辑注释等作用,一般不会在文档中提示。

单行注释 //

// 定义一个空字符串
var str = ""
// 修改str变量的值
str = "a new value"

多行注释 /* */

/*
这里是多行注释
多行注释里也可以成对出现
/*
子注释
*/
*/

结构性或者功能提示

MARK

MARK: 代码文件结构标记,可以显示文件的大致结构和模块,说明建议使用首字母大写

// MARK: - Properties
// MARK: - Initialization
// MARK: - IBAction Method
// MARK: - XXXDelegate

TODO

TODO: 待完成标记, 代表此处有需要完成的功能或者后续开发。

// TODO: - 待完成的功能
// TODO: - Need to finish

FIXME

FIXME: 检查标记, 通常用于需要检查的地方,比如临时修改变量为固定值方便测试,或者为了走通流程,注释部分代码等,都需要添加标记,方便后期提醒自己,万一忘了。最好上线前全局搜索检查下。

代码文件结构(Ctr + 6 )

文件结构

编译器提示

有些提示,我们希望在编译期间就看到定制提示或错误,我们就可以使用如下标记:

#error:编译器编译到这里就会停止,并展示携带的 message

#warning: 编译器编译到这里就会提示 message 信息

示例:

#warning("Needs to be refactored")
// some dodgy code here

#if !canImport(UIKit)
  #error("This framework requires UIKit!")
#endif
#error使用情况示例:SDK API key, 代码中必填信息提示,标记当前完成任务在哪里(以便下次接着开发)等情况。

原理解释参考diagnostics-warning-error,apple开源提案描述

文档注释

单行注释快捷键:⌘⌥/ 【 CMD + Alt + / 】

文档注释用于输出代码文档和阅读方便,规范的文档可以在Quick Help中看到或者Alt + 左键快速查看相关说明。更或者可以输出说明文档给别人使用

文档注释也分为单行和多行,不过根据苹果Swift 开源代码可以看出 基本都使用单行注释

文档注释的对象: 自定义类型、变量、方法等,但是重点还是方法说明

Tip: 由于文档注释通常是多行和多标识字段, 所以此时就可以用Xcode Code Snippet 代码段收藏与引用

单行注释 ///

文档说明,Xcode会根据注释产生相应文档和提示。

/// 用户信息
struct UserInfo {
    /// 昵称
    var nickname: String
    /// 性别 ture: 男,  false: 女
    var isMale: Bool
}

可惜的是Swift 没有发现对属性的行尾注释。

方法文档说明

/// 文档注释参考 【单行】
/// - parameter pram: 单参数
/// - returns : 返回结果是否成功 ture: 成功  false: 失败
///
/// 其他discussion 详细说明  // 【注意】必须隔一行
func singleLineComment(pram:String) -> Bool {
    print("注释参考")
    return true
}

多行注释 /** */

/**
 文档注释参考 【多行注释】  // 【注意:必须新起一行】
 - parameter p1: The number of Llamas spotted on the trip
 - parameter p2: The number of Llamas spotted on the trip
 - returns: 返回结果字符串数组
 
其他discussion说明  // 【注意】同样必须隔一行
 */
func text(p1:String , p2:Bool) -> [String] {
    return [String]()
    
}

支持 markdown 语法

除了使用关键字比如ruturns 来让文档更好看之外,我们还可以使用markdown丰富说明。单行和多行文档注释都支持markdown,但是这个时候个人建议就使用多行注释

 /**
 # 支持markdown
 # 一级标题
 ## 二级标题也可以的
 注释参考2
 隔一行表示换行d
 
 三个”***"代表一条分割线
 ***
 ## 使用示例
 ```
 let result = testComment2(pram: "参数1", param2: true))
 ```
 
 ****
 - important:这个很重要
 - returns: 有返回值
 - parameter pram: The cubes available for allocation
 - parameter param2: The people that require cubes

 */
func testComment2(pram:String, param2:Bool) -> Bool {
    print("markdown支持")
    return true
}

Quick Help 显示

Quick Help

Document Reference

支持文档跳转

Xcode 14后,支持制作自己项目的文档,我们可以在注释中通过使用``快速跳转,支持各种定义,方法

struct Student {
    var name: String
}

struct Class {
    var students: [Student] = []
    
    /// 添加一个学生
    /// - Parameter student: 学生``Student``
    mutating func insertStudent(_ student:Student) {
        students.append(student)
    }
}

在 Quick Help 中效果如下,点击连接即可跳转到对应文档。

截屏2023-04-06 11.29.13

playground 示例代码: gitee

swift Documentation

Playground注释

苹果官方文档: Xcode Help – Use playgrounds

Playgound 也支持markdown , 而且还可以做成跳转文档的模式。

比如,官网Sample Code, JSON与模型互转 下载即可

代码约束规范

对于平时的代码规范,Swift 语言可以使用SwiftLint 工具来约束。对代码习惯进行强约束,不符合的将提示警告或错误。

具体集成步骤参考 SwiftLint 官方文档

下面是 Cocoapod 检查脚本优化版本(只检查变动文件,避免全局检查,省略编译时间)

# Run SwiftLint
START_DATE=$(date +"%s")
 
SWIFT_LINT="${PODS_ROOT}/SwiftLint/swiftlint"
 
# Run SwiftLint for given filename
run_swiftlint() {
    local filename="${1}"
    if [[ "${filename##*.}" == "swift" ]]; then
        # ${SWIFT_LINT} autocorrect --path "${filename}"
        ${SWIFT_LINT} lint --path "${filename}"
    fi
}
 
if [[ -e "${SWIFT_LINT}" ]]; then
    echo "SwiftLint version: $(${SWIFT_LINT} version)"
    # Run for both staged and unstaged files
    git diff --name-only | while read filename; do run_swiftlint "${filename}"; done
    git diff --cached --name-only | while read filename; do run_swiftlint "${filename}"; done
else
    echo "${SWIFT_LINT} is not installed."
    exit 0
fi
 
END_DATE=$(date +"%s")
 
DIFF=$(($END_DATE - $START_DATE))
echo "SwiftLint took $(($DIFF / 60)) minutes and $(($DIFF % 60)) seconds to complete."

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.coloradmin.cn/o/439945.html

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈,一经查实,立即删除!

相关文章

React Native 混合ios android开发 及常用框架

英文文档:Setting up the development environment React Native 中文文档:集成到现有原生应用 React Native 中文网 ios 在集成过程中,需要修改package.json 和 Podfile,按文档中的内容,如果pod install过不了的…

用Kotlin 一步步抄作业写一个Redux

前言 我抄的作业 完全理解 redux(从零实现一个 redux) Issue #22 brickspert/blog GitHub 一.架构设计模式 1. mvc>mvp>mvvm->mvi 2.Redux实现类Mvi Android Mvi 与Redux对比,思想一致,单向数据流,单…

最优控制 3:最优控制理论中的极小值原理与动态规划

最优控制 3:使用极小值原理求解最优控制问题 引言极小值原理 t f t_f tf​ 固定的情况 t f t_f tf​ 自由的情况 动态规划连续系统 HJB 方程的推导 引言 经典变分法是一种特别强大的工具,但是它要求控制量必须可导且无界,这在很多问题中都是…

pandas读取列数不同的CSV文件

使用pandas读取每行不同列的CSV文件 对于序列模型而言,每条数据的大小都不一定相等,但对于一般的神经网络要求输入大小相等。目前的一种方法是选取当前数据集中最大长度的数据作为基准数据大小,其余的数据末尾补零来规范整个数据集每条数据的…

计算机:理解操作系统:内存篇(下)

内存 1. 指针与引用2. 进程的内存模型3. 幻象大师---操作系统4. 总结 本篇是 关于计算机内存最后一篇文章 什么是内存 C/C内存模型 堆区与栈区的本质 Java、Python等内存模型 Java内存模型 Jave中的堆区与栈区是如何实现的 Python内存模型 指针与引用 进程的内存模型 幻想大师-…

css tooltip (web.dev)

目录 版权介绍tool-tip在上居中动画效果宽度边界 tool-tip::after范围锥形渐变-webkit-mask尖角怎么来的? 附录完整代码 版权 本文为原创, 遵循 CC 4.0 BY-SA 版权协议, 转载需注明出处: https://blog.csdn.net/big_cheng/article/details/130262213. 介绍 https://web.dev…

【周末闲谈】AI作图,你真的了解它吗?

个人主页:【😊个人主页】 系列专栏:【❤️周末闲谈】 系列目录 ✨第一周 二进制VS三进制 ✨第二周 文心一言,模仿还是超越? ✨第二周 畅想AR 文章目录 系列目录前言AI绘画🤖🤖🤖工作…

[C++]:万字超详细讲解多态以及多态的实现原理(面试的必考的c++考点)

文章目录 前言一、多态的定义及实现1.多态的构成条件2.c11的override和final3.重载,重写,重定义的比较4.抽象类5.多态的原理6.多继承中的虚函数表7.动态绑定和静态绑定总结 前言 多态的概念: 多态的概念:通俗来说,就是…

【Linux】使用systemd设置开机自启动命令

目录 1 使用使用systemd实现开机自动运行命令1.1 新建一个.service文件1.2 编写.service文件1.2.1 [Unit]1.2.2 [Service]1.2.3 [Install] 1.3 启动服务并设置自启动 2 编写Systemd服务文件的要点2.1 Systemd服务文件的位置2.2 Systemd服务文件的格式2.3 Systemd服务文件的基本…

【基础】Kafka -- 基础架构及核心概念

Kafka -- 基础架构及核心概念 初识 KafkaKafka 基本架构Kafka 主题与分区主题与分区分区副本机制 Replica高水位 HW 生产者生产者客户端必要的参数配置消息的发送序列化分区器生产者拦截器 原理分析重要的生产者参数 消费者消费者与消费者组消费者客户端必要的参数配置订阅主题…

MySQL 按关键字进行截取

一、问题背景 取MySQL数据表中某个字段中的IP信息。 如:t_log 表中的 user_ip 字段值为 {“username”:“miracle”,“ip”:“110.230.128.186”},取出IP信息 110.230.128.186。 建表和初始化SQL语句,如下: SET NAMES utf8mb4…

GORM操作mysql数据库

对象就是程序的数据结构,关系是数据库。就是将程序的数据结构与数据库表对应起来。 在GORM是Go语言的ORM框架,将go的数据结构转化为数据库表,例如将结构体转化为数据库表。 引入gorm框架 远程下载gorm框架 go get -u gorm.io/driver/mysq…

HTTP中的Content-type详解

Content-Type Content-Type(MediaType),即是Internet Media Type,互联网媒体类型,也叫做MIME类型。在互联网中有成百上千中不同的数据类型,HTTP在传输数据对象时会为他们打上称为MIME的数据格式标签&#x…

关于java.io的学习记录(写入文本)

可以通过字节流(FileOutputStream)、字符流(OutputStreamWriter)、字符缓冲流(BufferedWriter)读取文本中的数据。 FileOutputStream写入文本 public void write(){String path "writeTest.txt"…

【是C++,不是C艹】 什么是C++ | C++从哪来 | 学习建议

💞💞欢迎来到 Claffic 的博客 💞💞 👉专栏:《是C,不是C艹》👈 前言: 我知道你急着学C,但你先别急,薛之谦认识认识C还是很有必要的。本期跟大家聊…

文件夹改名,如何在改名之后批量复制文件夹名称

在日常时候中会遇到给文件夹改名的时候,那么我们又如何在改名之后批量复制文件夹名称?今天就由小编来给大家分享一下操作办法。 首先第一步,我们要进入文件批量改名高手,并在板块栏里选择“文件夹批量改名”板块。 第二步&#xf…

SpringBoot 接入chatGPT API

SpringBoot 接入chatGPT API 一、准备工作二、补全接口示例三、申请API-KEY**四、JavaScript调用API**五、SpringBoot整合ChatGPT六、使用curl模拟请求ChatGPT平台已经为技术提供了一个入口了,作为一个Java程序员,我们第一时间想到的就是快速开发一个应用,接入ChatGPT的接口…

第十四天本地锁、Redis分布锁、Redisson锁三者的区别

一、为什么要有redis分布式锁,它解决了什么问题? 在传统单体架构的项目下,使用本地锁synchronized和lock锁就可以锁住当前进程,保证线程的安全性,但是本地锁解决不了分布式环境下多个服务资源共享的问题,而…

产品研发流程管理

先看一张图,该图适应绝大部分的产品的 研发流程 (需要的可以去下 产品研发流程| ProcessOn免费在线作图,在线流程图,在线思维导图) 该图详细描述了,不同阶段应该做什么,具体的来说,是确定了什么时候 “开会…

高精度人员定位系统源码,采用vue+spring boot框架,支持二次开发

智慧工厂人员定位系统源码,高精度人员定位系统源码,UWB定位技术 文末获取联系! 在工厂日常生产活动中,企业很难精准地掌握访客和承包商等各类人员的实际位置,且无法实时监控巡检人员的巡检路线,当厂区发生灾…