DocC的简单使用

在写3GShare中，由于刚开始使用MVC模式来写东西，对很多东西都不是很熟，经常写着写着就忘了自己在写什么，所以学了一下DocC来加快开发进度

什么是DocC

简单来说，DocC就是更高级的注释，虽然DocC 是专门为 Swift 代码写文档的工具，但是在OC中也是可以使用的，它可以将基于 Markdown 的文本转换为丰富的 Swift 框架和包文档

最重要的是，DocC 语法非常简单却很强大。不需要创建额外的文件或使用其他软件，一切都可以直接在 Xcode 中完成。

基础用法

最最简单的用法，把平时用的双斜杠注释换成三斜杠

完成了！

objectivec 复制代码

@interface loginAndRegisterModel : NSObject
/// 存储用户数据
@property (nonatomic, strong) NSMutableArray* usersInfo;
@end

写完这些注释后，你就可以在Xcode中按住 Option 键然后点击变量名，就能看到你写的文档了

当然方法也是同样的道理

objectivec 复制代码

/// 为第一个cell的滑动照片墙提供照片数组
- (NSArray*) providesImages;

添加更详细的说明

如果你想在解释说明中添加更多实现的细节，可以在第一段描述后空一行，然后继续写。这些内容会显示在帮助对话框的讨论部分

objectivec 复制代码

/// 保存按下按钮的状态
///
/// 把按钮的tag值存在对应节的数组中，方便之后查询
- (void)saveBtnPress:(NSInteger)tag andIndexPath:(NSIndexPath*)indexPath;

进阶用法：参数和返回值

描述参数

使用 - Parameters: 关键字可以描述函数的参数。注意破折号和冒号都是必需的，它们用作分隔符

但是在OC中似乎没有办法正常编译进去，这里使用swift演示一下

swift 复制代码

extension Array {
    /// 根据月份的日期返回一个随机元素，
    /// 该日期用于计算随机索引。
    ///
    /// stableRandom 函数在整个日期内始终返回相同的元素。
    /// 但是一旦日期发生变化，它的值就会改变。
    ///
    /// - Parameters:
    ///     - date: 用于随机化算法的日期。
    func stableRandom(using date: Date = .now) throws -> Element {
        // 实现代码...
    }
}

描述返回值和错误

返回值和错误在oc中可以正常描述，语法与参数一样

objectivec 复制代码

/// 检测注册信息是否可用
///  - Returns:
///  0：注册成功
///  1：邮箱有重复
///  2：用户名有重复
///  - Throws: 返回nil
- (NSInteger) isValidRegister:(user*) users;

DocC 的实际应用场景

合作开发

在合作开发中，对每个方法做好DocC能大大提高开发效率，可以让每个人方便的知道你的方法是干什么的，会返回什么结果，可能会出现什么样的错误

自己回顾代码

由于笔者刚开始使用MVC模式来写项目，常常会在三个甚至六个不同的文件里来回穿梭，在学了DocC后，就方便了许多，回头看自己写的DocC 文档可以让我快速的回忆起方法的作用

写在最后

当然，这里的介绍只是我觉得常用的部分，Apple在DocC方面有详细的教程，DocC的作用也远不止这些，感兴趣的同学可以移步Apple Developer

https://developer.apple.com/cn/videos/play/wwdc2021/10166