前言
在開發(fā)中編寫文檔注釋是一個很好的習慣 , 但是有些Coder會覺得寫一大片的注釋過于繁瑣和浪費時間 , 所以也就懶得去寫 , 為了制止無注釋的壞現(xiàn)象 , 下面我為大家講解幾種快速生成注釋的好方法 . (我似乎又維護了開發(fā)界的和平)
方法
VVDocumenter插件
VVDocumenter-Xcode是Xcode上一款快速添加標準注釋 , 并可以自動生成文檔的插件 . 有了VVDocumenter-Xcode , 規(guī)范化的注釋 , 只需要輸入三個斜線“///”就可以搞定 , 非常方面實用.
下面我來講解一下如何在Xcode7上使用.
首先從GitHub上下載VVDocumenter-Xcode 然后打開運行 , Xcode6的話可以無視下面的三步操作.
第一步:獲取xcode的UUID
在終端上輸入命令:
defaults read /Applications/Xcode.app/Contents/Info DVTPlugInCompatibilityUUID
執(zhí)行后就可以得到:
第二步 添加Xcode的uuid到VVDocumenter-Xcode的Info.plist文件
打開xcode插件所在的路徑:
~/Library/Application Support/Developer/Shared/Xcode/Plug-ins
(打開路徑的快捷鍵為 shift＋command＋g 然后輸入上面的地址）
選擇已經(jīng)安裝的插件例如VVDocumenter-Xcode , 右鍵"顯示包內(nèi)容".
找到 info.plist 文件 , 找到DVTPlugInCompatibilityUUIDs的項目 , 添加一個Item , Value的值為之前Xcode的UUID , 保存.
第三步 重啟Xcode
Xcode 6之后 , 重啟Xcode時會提示 "Load Bundle" 、 "Skip Bundle" , 這里必須選擇"Load Bundle" , 不然插件無法使用.
做到這一步 就已經(jīng)完成了VVDocumenter的配置 , 接下來你就可以在任何想要加注釋的地方輸入 "http:///" 了.
PS: 如果你選擇了 "Skip Bundles" , 那么你就算重新安裝也不會看到了 . 這是因為 Xcode里面的黑名單機制 . 別急 , 有解決辦法 , 看下面:
打開終端輸入以下命令:
defaults delete com.apple.dt.Xcode DVTPlugInManagerNonApplePlugIns-Xcode-7.2
__注意: 命令里的Xcode-7.2是你當前的Xcode版本號 , 務必填正確 . (此條命令結(jié)束 , 終端沒有反應 , 即沒有提示錯誤 , 就是正確的) __
接下來再重啟Xcode , 這次看到上面的提示再選擇 "Load Bundles" 就OK啦~
自定義注釋
如果你對注釋的格式等等有很高的要求 , 需要按照自定義的格式去添加 , 那么下面我教大家一種很實用的技巧.
首先我們在Xcode中編寫好我們需要的注釋格式 , 這里我簡單舉個例子:
/*!
* @brief <#簡要描述#>
*
* @param <#參數(shù)#>
*
* @return <#返回值#>
*/
其中 <# 內(nèi)容 #> 這個標簽在Xcode編碼區(qū)域會自動轉(zhuǎn)成可以實用 Tab 鍵切換的標簽 , 我們有時在調(diào)用某個方法時 參數(shù)部分那個效果的就是這個 .
接下來我們將這段注釋選中 :
將Xcode 右下角的窗口打開
直接將選中的這段注釋拖入右下角的窗口中:
這是我們會看到這樣的界面 , 其中Title 代表新添加的這個代碼段的標題 , Summary 為這個代碼段的簡介描述 , Platform為這個代碼段應用的平臺 ,
Completion Shortcut 這個代表使用的快捷方式 , Completion Scopes 這個代表使用的范圍.
這里我按照我的需求設(shè)置好了 , 下面我們演示一下使用效果 , 當我在代碼編寫窗口中 打出我們之前設(shè)置好的快捷方式關(guān)鍵字 , 代碼自動填充提示框就會提示出剛才我添加的代碼段標題 , 這是直接點擊回車鍵 , 剛剛那一段注釋就自動為我們添加好了.
怎么樣 ? 是不是很方便 . 這種方法需要我們事先按照自己的需求配置好后才能使用 , 不過自由度相比插件而已要高很多 , 不光是注釋 , 比如我們平時開發(fā)時 使用頻率較高 格式變化不大的代碼段都可以使用這個方法去實現(xiàn) , 這里不再一一介紹了 , 如果你感興趣的話 可以自己慢慢去發(fā)掘.
修改Xcode默認注釋
當你創(chuàng)建一個新的.h .m文件時 , 你可以看到文件頂部Xcode為我們自動添加好了一些描述的注釋 , 但這些注釋僅僅是用來描述這個文件 , 無法滿足我們生成文檔時的一些需求 , 下面我來為大家講解如何將Xcode默認注釋修改成我們需要的格式.
首先右鍵 Xcode -> 選項 -> 在Finder中打開 -> 右鍵 -> 顯示包內(nèi)容Contents -> Developer -> Platforms -> iPhoneOS.platform -> Developer -> Library -> Xcode -> Templates -> File Templates
仔細看看這些文件夾名稱 , 有木有很熟悉的感覺 ? ? 沒錯 就是這個:
選中Source -> Cocoa Touch Class.xctemplate
這個目錄下面有很多后綴名為Objective-C跟Swift的文件夾 , 這么多怎么看呢 ? 我們先打開NSObjectObjective-C下面的FILEBASENAME
上面那綠油油的注釋就是我們要修改的東西了 , 注意它的格式 , 跟我們創(chuàng)建文件的頭部注釋是一樣的.
這里用到了幾個系統(tǒng)的預處理宏定義 .
包括: __FILENAME__、__PROJECTNAME__、__FULLUSERNAME__、__DATE__和__COPYRIGHT__ , 分別表示的是文件名、項目名稱、系統(tǒng)用戶全稱、當前日期和版權(quán)聲明 , 這些宏定義可以用在我們修改之后的注釋中 . 我把它修改成下面這樣:
這樣就符合我們需要的文檔注釋的格式了 , 這里有一點要說一下 , 在你修改內(nèi)容的時候可能會這樣提示你:
這個提示的意思是說你沒有足夠的權(quán)限去修改 , 這時候你可以通過終端去修改文件的權(quán)限 , 當然還有一種更方便的方法 , 你右鍵要修改的文件 , 將它拷貝到隨便一個地方(我拷貝到了桌面) , 然后打開拷貝的這個文件 , 你會發(fā)現(xiàn)可以隨意修改了 , 這時你修改好后 直接將這個文件拖到原文件所在的文件夾中 , 替換原文件 (此時可能需要你輸入一下密碼).
退出Xcode重新運行 , 然后創(chuàng)建一個新的類 , 我們就會發(fā)現(xiàn)新的類文件格式:
這樣我們需要的頭文件注釋文檔已經(jīng)自動生成了 , 而且是一次操作 , 永久受益 . 大家可以依照我演示的這個示例去修改其他的類文件 , 在@interface的注釋模板上加上規(guī)范類信息的注釋文檔 , 就可以直接創(chuàng)建類的注釋文檔 . 是不是很實用 ?
總結(jié)
善于利用各種小工具 小技巧來為我們解決繁瑣而重復的工作 , 可以讓我們更加專注于開發(fā) , 不但節(jié)約了時間 , 還規(guī)范了不容易注意的細節(jié) .
相關(guān)文章
我是LEE , 如果你還有更好的建議 歡迎給我留言 , 如果喜歡記得點贊喲 ! 么了個噠~
