讀古今文學網 > iOS編程基礎:Swift、Xcode和Cocoa入門指南 > 8.4 快速幫助 >

8.4 快速幫助

快速幫助是關於某個主題的縮略文檔,主題通常是個符號名。它與當前所選或插入點有關,如果快速幫助查看器打開了,那麼它就會自動出現在快速幫助查看器中(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章)。