快速幫助是關於某個主題的縮略文檔,主題通常是個符號名。它與當前所選或插入點有關,如果快速幫助查看器打開了,那麼它就會自動出現在快速幫助查看器中(Command-Option-2)。比如,如果你正在編輯代碼,而插入點或所選內容位於CGPointMake中,那麼CGPointMake的文檔就會出現在快速幫助查看器中(如果查看器可見)。
如果在nib編輯器中選擇了界面對像(編輯項目或目標的同時又在構建設置)並打開了快速幫助查看器,那麼也可以使用快速幫助。
快速幫助文檔還可以顯示為一個彈出窗口,這樣就無須使用快速幫助查看器了。選中某個詞並選擇Help→Quick Help for Selected Item(Command-Control-Shift-?)。此外,還可以按下Option鍵並將鼠標指針懸浮在某個詞上,直到鼠標指針變成一個問號(這個詞會變成藍色,同時會有一個點下劃線);然後按住Option鍵並單擊這個詞。
在編寫Swift代碼時,快速幫助是非常重要的。如果單擊其類型已經推斷出來的某個Swift變量的名字,那麼快速幫助就會顯示出推斷出的類型(如圖3-1所示)。這有助於理解編譯錯誤和其他問題。
快速幫助文檔還包含了鏈接。比如,單擊Reference鏈接會在文檔窗口中打開整個文檔。
可以將自己編寫的代碼的文檔加到快速幫助中。要做到這一點,請在聲明前加上註釋/**...*/(此外,還可以使用以///開頭的單行註釋)。可以在註釋中使用Markdown格式(參見http://daringfireball.net/projects/markdown/syntax);使用Markdown是Xcode 7新增的功能。註釋會變成快速幫助的描述部分;某些列表項(以*或是-開頭,後跟空格的段落)會被特殊對待:
·以「Parameter[paramname]:」開頭的段落會成為Parameters域的一部分。
·以「Throws:」開頭的段落會成為Throws域的一部分。
·以「Returns:」開頭的段落會成為Returns域的一部分。
比如,下面是帶有前置註釋的函數聲明:
圖8-2:將自定義文檔添加到快速幫助中
/** Many people would like to dog their cats. So it is *perfectly* reasonable to supply a convenience method to do so: * Because it's cool. * Because it's there. * Parameter cats: A string containing cats * Returns: A string containing dogs */ func dogMyCats(cats:String) -> String { return "Dogs" }
註釋起始處的兩個星號表示這是個文檔,註釋的位置會自動將其關聯到dogMyCats方法上。星號所包圍的單詞會被格式化為斜體;星號段落會變成無序列表;最後兩個段落會成為特殊域。結果就是在代碼中選中了dogMyCats後,其實現會顯示在快速幫助中(如圖8-2所示)。說明的第一部分也會顯示在代碼完成部分中(參見第9章)。