前言
碼農(nóng)總是在搬磚挺峡，日復(fù)一日葵孤，年復(fù)一年，有的時(shí)候都會麻木橱赠。
代碼大家都會寫尤仍，但是把注釋寫好卻是一個(gè)技術(shù)活。
下面這段話狭姨，很好的說明了寫好注釋的感覺：
注釋代碼很像清潔你的廁所——你不想干宰啦，但如果你做了苏遥，這絕對會給你和你的客人帶來更愉悅的體驗(yàn)∩哪＃—— Ryan Campbell
今天給大家聊的就是在Xcode中田炭，代碼注釋編寫小技巧。
Objective-C的代碼注釋
很久很久以前纺裁，在Xcode還可以安裝插件的時(shí)代诫肠，iOSer都通過VVDocument來編寫代碼注釋的司澎。
代碼注釋的風(fēng)格一般都是這樣的欺缘，代碼出自IQKeyboardManager/IQBarButtonItem
#import <UIKit/UIBarButtonItem.h>
@class NSInvocation;
/**
IQBarButtonItem used for IQToolbar.
*/
@interface IQBarButtonItem : UIBarButtonItem
/**
Boolean to know if it's a system item or custom item
*/
@property (nonatomic, readonly) BOOL isSystemItem;
/**
Additional target & action to do get callback action. Note that setting custom target & selector doesn't affect native functionality, this is just an additional target to get a callback.
@param target Target object.
@param action Target Selector.
*/
-(void)setTarget:(nullable id)target action:(nullable SEL)action;
/**
Customized Invocation to be called when button is pressed. invocation is internally created using setTarget:action: method.
*/
@property (nullable, strong, nonatomic) NSInvocation *invocation;
@end
OC的注釋是通過/** */這樣的形式進(jìn)行編寫的。分隔符使用的是這種風(fēng)格：
#pragma mark - 這個(gè)是一個(gè)分割符
需要注意的是這個(gè)-非常的重要挤安，通過這個(gè)-谚殊，在查看代碼的時(shí)候，可以生成分隔線蛤铜，讓代碼結(jié)構(gòu)看的更為清晰嫩絮。
Swift的代碼注釋
隨著Swift語言發(fā)布，在Swift中編寫注釋的風(fēng)格就所有不同了：
extension NSObject {
/// 對象獲取類的字符串名稱
public var className: String {
return runtimeType.className
}
/// 類獲取類的字符串名稱
public static var className: String {
return String(describing: self)
}
/// NSObject對象獲取類型
public var runtimeType: NSObject.Type {
return type(of: self)
}
/// 這是一個(gè)例子函數(shù)
/// - Parameter arg:
/// - Parameter argument: 傳入Int類型的參數(shù)
/// - Returns: 返回Int類型的參數(shù)
public func afunction(argument: Int) -> Int {
return argument
}
}
Swift的注釋是通過/// 這樣的形式進(jìn)行編寫的围肥。分隔符使用的是這種風(fēng)格：
//MARK: - 綁定
Swift中的//MARK:這個(gè)-也是起到生成分隔線的作用剿干。
Objective-C和Swift的注釋風(fēng)格現(xiàn)在已經(jīng)統(tǒng)一
如果你現(xiàn)在通過alt+cmd+/在OC和Swift中編寫注釋的時(shí)候，就會發(fā)現(xiàn)現(xiàn)在的注釋都變成了Swift的這個(gè)中風(fēng)格了：
我個(gè)人建議是：以前代碼注釋就讓它去吧穆刻，現(xiàn)在就都是用這個(gè)統(tǒng)一風(fēng)格置尔。
快速修改注釋
一個(gè)函數(shù)寫好了，注釋也寫好氢伟，但是有的時(shí)候計(jì)劃沒有變化快榜轿，函數(shù)添加了新的參數(shù)，這個(gè)注釋難道要手動添加朵锣？別急谬盐，其實(shí)Xcode也為我們提供了快捷方式，我們繼續(xù)看例子诚些，這個(gè)函數(shù)我在之前的基礎(chǔ)上添加了一個(gè)num參數(shù)飞傀，但是注釋還是之前的樣子：
cmd+鼠標(biāo)左鍵點(diǎn)擊，我們可以看到左側(cè)出現(xiàn)了一個(gè)菜單诬烹，點(diǎn)擊Add Documentation
大家有興趣可以把菜單的選項(xiàng)都點(diǎn)擊試試椅您，也許有意外的驚喜外冀，比如Convert Function to Async，await/async掀泳。
參考文檔
VVDocumenter（https://github.com/onevcat/VVDocumenter-Xcode）
