DocC的簡單使用

在寫3GShare中，由于剛開始使用MVC模式來寫東西，對很多東西都不是很熟，經常寫著寫著就忘了自己在寫什么，所以學了一下DocC來加快開發進度

什么是DocC

簡單來說，DocC就是更高級的注釋，雖然DocC 是專門為 Swift 代碼寫文檔的工具，但是在OC中也是可以使用的，它可以將基于 Markdown 的文本轉換為豐富的 Swift 框架和包文檔

最重要的是，DocC 語法非常簡單卻很強大。不需要創建額外的文件或使用其他軟件，一切都可以直接在 Xcode 中完成。

基礎用法

最最簡單的用法，把平時用的雙斜杠注釋換成三斜杠

完成了！

@interface loginAndRegisterModel : NSObject
/// 存儲用戶數據
@property (nonatomic, strong) NSMutableArray* usersInfo;
@end

寫完這些注釋后，你就可以在Xcode中按住?Option?鍵然后點擊變量名，就能看到你寫的文檔了

當然方法也是同樣的道理

/// 為第一個cell的滑動照片墻提供照片數組
- (NSArray*) providesImages;

添加更詳細的說明

如果你想在解釋說明中添加更多實現的細節，可以在第一段描述后空一行，然后繼續寫。這些內容會顯示在幫助對話框的討論部分

/// 保存按下按鈕的狀態
///
/// 把按鈕的tag值存在對應節的數組中，方便之后查詢
- (void)saveBtnPress:(NSInteger)tag andIndexPath:(NSIndexPath*)indexPath;

進階用法：參數和返回值

描述參數

使用?- Parameters:?關鍵字可以描述函數的參數。注意破折號和冒號都是必需的，它們用作分隔符

但是在OC中似乎沒有辦法正常編譯進去，這里使用swift演示一下

extension Array {/// 根據月份的日期返回一個隨機元素，/// 該日期用于計算隨機索引。////// stableRandom 函數在整個日期內始終返回相同的元素。/// 但是一旦日期發生變化，它的值就會改變。////// - Parameters:///     - date: 用于隨機化算法的日期。func stableRandom(using date: Date = .now) throws -> Element {// 實現代碼...}
}

描述返回值和錯誤

返回值和錯誤在oc中可以正常描述，語法與參數一樣

/// 檢測注冊信息是否可用
///  - 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