Swift   发布时间:2022-03-31  发布网站:大佬教程  code.js-code.com
大佬教程收集整理的这篇文章主要介绍了Swift 文档注释规范大佬教程大佬觉得挺不错的,现在分享给大家,也给大家做个参考。

概述

代码的结构和组织关乎了开发童鞋们的节操问题。明确和一致的代码表示了明确和一贯的思想。编译器并没有一个挑剔的口味,但当谈到命名,空格或文档,人类的差异就体现出来了。 NSHipster 的读者无疑会记得去年发表的关于文档的文章,但很多东西已经在 Xcode 6 中发生了变化(幸运的是,基本上算是变得更好了)。因此,这一周,我们将在此为嗷嗷待哺的 Swift 开发者们记录一下文档说明。 好了,来让我们

代码的结构和组织关乎了开发童鞋们的节操问题。明确和一致的代码表示了明确和一贯的思想。编译器并没有一个挑剔的口味,但当谈到命名,空格或文档,人类的差异就体现出来了。

NSHipster 的读者无疑会记得去年发表的关于文档的文章,但很多东西已经在 Xcode 6 中发生了变化(幸运的是,基本上算是变得更好了)。因此,这一周,我们将在此为嗷嗷待哺的 Swift 开发者们记录一下文档说明。

好了,来让我们仔细看看。


从 00 年代早期,Headerdoc就一直作为苹果首选的文档标准。从 Perl 脚本解析勉强的Javadoc注释作为出发点,Headerdoc 最终成为了苹果在线文档及 Xcode 中的开发者文档的后台引擎。

随着 WWDC 2014 的发布,开发者文档被翻修并进行了时尚的新设计,包含了 Swift 和 Objective-C 的切换。 (如果你看过任何新的 iOS 8 的在线 API,那你已经见过这个新设计了)

真正让人意外的是,文档的格式也发生了变化。

在 Swift 的代码调用快速文档 (Quick Documentation)(⌥ʘ)时 Headerdoc 没有正确解析注释:

Swift
/**
 让我们随便来写点什么.

 @param 啦啦啦啦,这货是参数。

 @return 咯咯咯咯,这货是返回值。
*/
func foo(bar: String) -> AnyObject { ... }

但如果修改一下标记方式,就可以被正确解析:

:param: 啦啦啦啦,这货是参数。 :returns: 咯咯咯咯,这货是返回值。 那么,这个陌生的新文件格式是个什么情况?事实证明,sourceKit(Xcode 使用的私有框架,在此前以其高 FPS 崩溃闻名)包括一个解析reStructuredText的基本解析器。然仅实现了specification一个子集,但涵盖基本的格式已经足够了。

基本标记

文档注释通过使/** ... */的多行注释或///...的单行注释来进行区分。在注释块里面,段落由空行分隔。无序列表可由多个项目符号字符组成:-+*等,同时有序列表使用阿拉伯数字(1,2,3,...),后跟一个点符1.或右括号1)或两侧括号括起来(1)

你可以制作 *斜体*,**粗体**,或 `代码` 的字体风格.
- 列表很不错, - 但最好不要叠套 - 子列表的格式 - 就不太好了. 1. 有序列表也一样 2. 对那些有序的东西来说; 3. 阿拉伯数字 4. 是唯一支持的格式. */

定义与字段列表

定义和字段列表跟 Xcode 里的快速文档弹出@L_675_25@显示的差不多,定义列表会更紧凑一些:

DeFinition list 一些术语以及它们的定义. Format 左对齐术语,放在缩进的定义下面. :Field header: 字段列表隔开一些。 :Another field: 字段列表可以紧跟开始,不需要另起一行并缩进。 随后缩进的行也被视为@L_675_25@的一部分. */

两个特殊字段用于记录参数和返回值:分别为::param::returns::param:后跟的是参数的名称,然后是说明。返回值没有名字,所以:returns:后就是说明:

重复一个字符串 `times` 次. :param: str 需要重复的字符串. :param: times 需要重复 `str` 的次数. :returns: 一个重复了 `str` `times` 次的新字符串. repeatString(str: String, times: Int) -> String { return join("", Array(count: times,210)">repeatedValue: str)) }

代码

代码块也可以嵌入到文档的注释里,这对于演示正确的使用方式或实现细节很有用。用至少两个空格来插入代码块:

`Shape` 实例的面积. 计算取决于该实例的形状。如果是三角形,`area` 将相当于: let height = triangle.calculateHeight() let area = triangle.base * height / 2 var area: CGFloat { get }

我的自行车类的新文档

当这个应用在整个类的时候看起来怎么样?事实上,看起来相当的不错:

import Foundation

/// 
0
0
猜你在找
查看评论
* 以上用户言论只代表其个人观点,不代表CSDN网站的观点或立场

大佬总结

以上是大佬教程为你收集整理的Swift 文档注释规范全部内容,希望文章能够帮你解决Swift 文档注释规范所遇到的程序开发问题。

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

本图文内容来源于网友网络收集整理提供,作为学习参考使用,版权属于原作者。
如您有任何意见或建议可联系处理。小编QQ:384754419,请注明来意。