前言

在一個(gè)應(yīng)用的整個(gè)開發(fā)過程中涉及到了無數(shù)的步驟。其中一些是應(yīng)用的說明 , 圖片的創(chuàng)作 , 應(yīng)用的實(shí)現(xiàn) , 和實(shí)現(xiàn)過后的測(cè)試 . 寫代碼可能組成了這個(gè)過程的絕大部分 , 因?yàn)檎撬o了應(yīng)用生命 , 但是這樣還不夠 , 與它同等重要的還有代碼的注釋和文檔編寫 . 不管代碼寫的有多好 , 如果缺少了對(duì)應(yīng)的好的注釋文檔 , 很有可能在將來帶來麻煩 . 不幸的是 , 許多開發(fā)者都忽視或忽略了代碼文檔的重要性 , 而這非常糟糕 , 因?yàn)楹玫某绦虿粌H僅是好的代碼 . 它需要更多的東西.

對(duì)于注釋的重要性 這里我不再過多闡述 , 有興趣的話就看看下面引用的一段對(duì)注釋重要性的解釋:

談到編寫注釋文檔，顯然我不是說僅僅簡(jiǎn)單的在實(shí)現(xiàn)文檔里添加幾行注釋?？隙ㄊ歉嗟臇|西。但是首先，為什么對(duì)代碼進(jìn)行注釋這么重要？好吧，這里有兩個(gè)情景：不管你是單獨(dú)工作，或者你是團(tuán)隊(duì)的一份子。讓我們來分別解釋一下。

如果你是一個(gè)正在開發(fā)的應(yīng)用的唯一開發(fā)者，有理由相信寫注釋文檔會(huì)消耗時(shí)間，所以忽略不做會(huì)讓你更迅速完成目標(biāo)。除此之外，很容易說服自己既然都是獨(dú)立開發(fā)者了沒有太大必要來做注釋文檔。但是相信我，這將會(huì)是在應(yīng)用開發(fā)期間做的最壞的決定。假設(shè)你成功的開發(fā)完成了應(yīng)用，無論是在app store上銷售或者賣給你的客戶，然后你把它保存起來。六個(gè)月后，你必須要通過添加幾個(gè)新功能來創(chuàng)建一個(gè)這個(gè)應(yīng)用的新版本。當(dāng)你重新打開這個(gè)工程然后查看已有的代碼，在你寫下第一行新代碼之前一段時(shí)間，你會(huì)意識(shí)到一個(gè)殘酷的真相：你幾乎不記得任何東西！你做過什么，你怎么做的，為什么要這么做，都會(huì)很難回想起來！你必須通過一個(gè)痛苦的方法來在腦袋里重新喚起這個(gè)工程，這個(gè)方法就是從工程的最開始，一行行的“解密”你的實(shí)現(xiàn)代碼。僅僅是幾行注釋根本沒什么幫助，最終直到你理解所有東西之前會(huì)用很長(zhǎng)的時(shí)間且花掉許多精力。正在讀這些內(nèi)容的很大一部分的你們都可能遇到過那種情況，而且我很肯定的給你說過去我也遇到過。這種情況真的是噩夢(mèng)一樣，那時(shí)你經(jīng)常想干脆從頭開始做一個(gè)工程算了。當(dāng)然，這里提到的場(chǎng)景可能僅僅會(huì)是一個(gè)...場(chǎng)景，只要我們花一點(diǎn)點(diǎn)時(shí)間來編寫合適的注釋文檔。

另一方面，如果你是團(tuán)隊(duì)里的一員來開發(fā)工程，那么避開給代碼寫注釋文檔將會(huì)是災(zāi)難性的。當(dāng)你給其他開發(fā)者分享代碼時(shí)，你必須解釋你的觀點(diǎn)（在代碼里），當(dāng)時(shí)做了什么，是怎樣做的，當(dāng)然其他的開發(fā)者也被要求做同樣的事情。沒有一個(gè)情形是大項(xiàng)目的開發(fā)者們對(duì)后面開發(fā)者們開發(fā)的代碼都有全面的了解，因?yàn)槿羰沁@樣，將會(huì)浪費(fèi)掉很多不必要的時(shí)間。因此，在這種情況下的編寫注釋代碼一方面就像是做交流，另一方面也是幫助團(tuán)隊(duì)里的其它開發(fā)者了解你的代碼的含義。畢竟，每個(gè)程序員編寫代碼的風(fēng)格都跟其他人不一樣，所以表達(dá)清楚你的代碼功能是件必須做的任務(wù)。

概述

在開始之前 , 讓我說明兩件事情 . 第一，我不是試圖讓你偏執(zhí)的寫文檔 , 而是說服你編寫合適的注釋將會(huì)提高你的編程生涯 . 第二 , 編寫代碼注釋文檔是你必須接受的習(xí)慣 , 而絕對(duì)不是浪費(fèi)時(shí)間 .

注釋的使用說明

正如你知道的，在Objective-C 和 Swift中寫一條注釋的最簡(jiǎn)單辦法是用兩條斜杠：

 // 我是一條注釋.

你可以 (且必須) 像上面那樣來放置你的注釋 , 以便分清每個(gè)部分 . 但是 , 當(dāng)談到代碼注釋文檔 , 我肯定不是指的上面的注釋 . 如果整個(gè)教程都專注于此肯定毫無意義 . 注釋文檔意味著以結(jié)構(gòu)化的方法使用特殊的關(guān)鍵字 , 也叫標(biāo)簽來寫注釋 , 使用特殊的符號(hào)來標(biāo)示注釋區(qū)域 , 因此編譯器可以完美的理解這個(gè)過程 . 只有一些簡(jiǎn)單的規(guī)則需要遵守 . 上面操作的所有結(jié)果就是你的注釋文檔可以在三個(gè)不同的地方展示:

1. 在Utilities面板的Quick Help Inspector 里.
2. 當(dāng)你按下Option鍵然后點(diǎn)擊方法 , 類或?qū)傩悦麜r(shí)彈出的幫助菜單 Help Popup 里.
3. 在代碼實(shí)現(xiàn)彈出框里.

除此之外 , 合適的代碼注釋讓你可以使用眾多的工具來為你的應(yīng)用創(chuàng)建完整的HTML文檔 , 例如the HeaderDoc 和 Doxygen . 它們兩個(gè)后面會(huì)提到.

當(dāng)使用 Objective-C 寫代碼時(shí)有三種可能的方法來標(biāo)示一個(gè)注釋文檔區(qū)域:

把你的注釋包含在/** 你的注釋 */ 塊里。
把你的注釋包含在 /*! 你的注釋 */塊里。
以三條斜杠 ///開始的注釋行

在這個(gè)教程實(shí)例中我們將會(huì)用第二種方法來寫我們的注釋文檔 . 我選擇它出于兩個(gè)原因 : 第一 , 它是唯一一個(gè)能被 HeaderDoc 識(shí)別的格式 , 而且如果注釋塊不是以它開頭 , 幫助頁(yè)也不會(huì)被生成 . 第二 , 盡管 Doxygen 更傾向于第一種格式 , 它也能識(shí)別第二種 . 因此 , 第二種格式將會(huì)在兩種方法下都適用 . 第三種格式通常在注釋一行時(shí)用到 , 例如屬性值時(shí) , 因此 , 我們還是堅(jiān)持用第二種格式.

現(xiàn)在 , 當(dāng)寫注釋文檔時(shí) , 你可以使用特定的關(guān)鍵值 (或標(biāo)簽) . 標(biāo)簽被分為兩個(gè)大類 : 第一個(gè)是 top level 標(biāo)簽 , 它可以用來指定哪種類型的代碼被注釋了 , 例如類 , 結(jié)構(gòu)體 , 文件 , 等等 . 注意top level標(biāo)簽不是必須使用，但是肯定會(huì)幫助導(dǎo)出工具 (例如 HeaderDoc 和 Doxygen) 創(chuàng)建出更好的結(jié)果 . 第二個(gè)是second level標(biāo)簽 , 它指定了每個(gè)注釋文檔塊的細(xì)節(jié) . 這個(gè)類型的標(biāo)簽正是你需要的 , 因?yàn)槊恳粋€(gè)都定義了另外的注釋文檔部分.

下面我給出了最重要的second level標(biāo)簽 , 但是注意了這并不是全部 . 我們稍后會(huì)看到一些 top level標(biāo)簽 . 我這里列出來的是最常用到的:

• @brief: 使用它來寫一段你正在文檔化的method, property , class , file , struct , 或enum的短描述信息.
• @discussion: 用它來寫一段詳盡的描述 . 如果需要你可以添加換行 .
• @param: 通過它你可以描述一個(gè) method 或 function的參數(shù)信息 . 你可以使用多個(gè)這種標(biāo)簽.
• @return: 用它來制定一個(gè) method 或 function的返回值.
• @see: 用它來指明其他相關(guān)的 method 或 function . 你可以使用多個(gè)這種標(biāo)簽.
• @sa: 同前一條類似.
• @code: 使用這個(gè)標(biāo)簽 , 你可以在文檔當(dāng)中嵌入代碼段 . 當(dāng)在Help Inspector當(dāng)中查看文檔時(shí) , 代碼通過在一個(gè)特別的盒子中用一種不同的字體來展示 . 始終記住在寫的代碼結(jié)尾處使用@endcode標(biāo)簽.
• @remark:在寫文檔時(shí)，用它來強(qiáng)調(diào)任何關(guān)于代碼的特殊之處.

你可以在 這里 （HeaderDoc User Guide）找到包含所有支持的標(biāo)簽的列表.

注意 : @符號(hào)是每個(gè)標(biāo)簽的前綴 . 同樣 , 你也可以在文本中使用特殊字符switches , 這樣就可以改變它的類型和格式。例如，Text 以會(huì)讓 Text單詞成為黑體，同時(shí)Text也會(huì)讓 Text 單詞的類型為italic. 有趣的是你也可以把部分文本以代碼形式展現(xiàn)（不是代碼段），如果寫下@cText，當(dāng)幫助文檔在Xcode上展現(xiàn)時(shí)，它會(huì)導(dǎo)致展示一個(gè)不同的字體格式。

除開上面說的 , 你也可以替換@符號(hào)為反斜杠(\) . 那樣的話標(biāo)簽就會(huì)像這樣被展示： \brief, \param, \return,等等 . 注意反斜杠最常在 Doxyten 文檔系統(tǒng)里面被使用 , 而@符號(hào)常在 HeaderDoc 里面被使用 . 在這里我們會(huì)在所有地方使用@ , 因?yàn)樗趦蓚€(gè)系統(tǒng)中都通用.

注釋的使用演示

屬性:

讓我們看看以上我提到的內(nèi)容是怎樣使用的 . 首先我聲明一個(gè)屬性:

@property (nonatomic , copy ) NSString *name;

然后如下面所示添加注釋文檔:

/*! @brief 用戶姓名屬性 */

@property (nonatomic , copy ) NSString *name;

然后到這個(gè)類某一個(gè)方法中 , 開始輸入這個(gè)屬性 . 你將看到在代碼填充彈出框里我們剛剛寫下的注釋就在那里了.

而且不僅這樣 . 當(dāng)在鍵盤上按住 Option 鍵，點(diǎn)擊name屬性就會(huì)讓幫助窗口彈出：

更多的 , 如果在Utilities面板打開 Help Inspector , 你會(huì)在那里找到相同的文檔.

注意在上面的注釋當(dāng)中 @brief 標(biāo)簽可以被去掉而不會(huì)導(dǎo)致任何問題 . 意味著下面的這條注釋也是有效的:

/*! 用戶姓名屬性 */

@property (nonatomic , copy ) NSString *name;

同樣的，下面的也一樣:

/** 用戶姓名屬性 */

@property (nonatomic , copy ) NSString *name;

而且下面的這條也一樣:

/// 用戶姓名屬性 */

@property (nonatomic , copy ) NSString *name;

方法:

我來演示一下方法注釋的示例 , 那么只是公有方法（在頭文件里的）的文檔是可見的 . 無論你在類的私有部分中寫的任何文檔在 Xcode 幫助文檔里都是可見的 , 但是任何實(shí)現(xiàn)部分都沒有被導(dǎo)出到注釋文檔里 . 所以 , 記住這些 , 現(xiàn)在讓我們?cè)贚aunchViewController.h 文件里定義一個(gè)公有方法:

- (NSString *)stringToMD5:(NSString *)fromString;

很顯然 , 這個(gè)方法將會(huì)把一個(gè)字符串轉(zhuǎn)換為MD5加密的 . 現(xiàn)在我們來添加注釋文檔:

/*!
 *  @brief  MD5加密字符串
 *
 *  @discussion 傳入一個(gè)字符串對(duì)象 并通過MD5加密算法對(duì)其進(jìn)行    16位加密
 *
 *  @param  fromString為要加密的字符串對(duì)象
 *
 *  @return 16位小寫加密字符串
 */
- (NSString *)stringToMD5:(NSString *)fromString;

注意在上面我們使用HTML開關(guān)來讓所有包含的文字分別是粗體和斜體。同樣注意我們是怎樣使用@c開關(guān)來標(biāo)識(shí)內(nèi)嵌代碼

接下來我們這在ViewController.m文件中實(shí)現(xiàn)這個(gè)方法:

#pragma mark - MD5加密字符串

- (NSString *)stringToMD5:(NSString *)fromString{

    const char *cStr = [fromString UTF8String];

    unsigned char result[CC_MD5_DIGEST_LENGTH];

    CC_MD5(cStr, (CC_LONG)strlen(cStr), result);

    return [[NSString stringWithFormat:@"%02X%02X%02X%02X%02X%02X%02X%02X%02X%02X%02X%02X%02X%02X%02X%02X",
         result[0], result[1], result[2], result[3],
         result[4], result[5], result[6], result[7],
         result[8], result[9], result[10], result[11],
         result[12], result[13], result[14], result[15]
         ] lowercaseString];

}

同樣我們把光標(biāo)放到方法名上，在Quick Help Inspector里查看：

Help Inspector

option

方法中調(diào)用這個(gè)函數(shù) , 那么就可以在函數(shù)自動(dòng)填充窗口里看到簡(jiǎn)介描述:

填充窗口描述

很棒 , 是不是 ? 可以想象你的代碼那樣文檔化后會(huì)變得多有幫助 且能自我解釋清楚代碼意義 , 特別是當(dāng)你同其他團(tuán)隊(duì)人員一起工作時(shí).

下面我們玩點(diǎn)有意思的 , 為這個(gè)注釋增加點(diǎn)更直觀的效果:

代碼框 + 備注

沒錯(cuò) 代碼框 和 備注 , 通過@code - @endcode標(biāo)簽 和 @remark標(biāo)簽 可以讓我們的自己的文檔注釋和Xcode默認(rèn)文檔比起來毫不遜色.

在前面部分我們?yōu)g覽了寫屬性或方法時(shí)需要遵守的記錄文檔規(guī)則 . 我故意從屬性和方法開始介紹編寫文檔 , 因?yàn)槟愕拇蟛糠珠_發(fā)時(shí)間都是消耗在那里?，F(xiàn)在我們已經(jīng)看到了最主要的部分 , 現(xiàn)在繼續(xù)看看怎樣對(duì) files , classes , structs 和 enums 添加注釋.

讓我們從files開始 , 怎樣在Objective-C中寫下能提供信息的文檔 . 當(dāng)同其他人分享編程工作時(shí) , 或者當(dāng)你以開放源代碼組件形式分發(fā)代碼時(shí) , 那么添加file documentation就是必須的 , 因?yàn)檫@是最佳的地方來向你的開發(fā)伙伴或者使用你代碼的人提供明確的信息 . 通常 , 你將要更關(guān)注header 文件 (.h) 以及在它里面的描述信息 , 因?yàn)檫@些會(huì)保留在將被導(dǎo)出的最終文檔里 (并不在Xcode里) ; 但是 , 這并不代表你不需要在implementation文件中添加描述信息 . 不要忘記當(dāng)在Xcode中打開工程時(shí) , 所有的東西都在那兒 , 不僅僅是header 文件 , 因此保證你不會(huì)留下沒被記錄文檔的部分 . 除此之外 , 實(shí)現(xiàn)部分不會(huì)在導(dǎo)出文檔中看到 , 但是所有文件的描述信息始終都是可見的.

文件:

讓我介紹一些當(dāng)你在記錄一個(gè)文件時(shí)會(huì)用到的新標(biāo)簽:

• @file: 使用這個(gè)標(biāo)簽來指出你正在記錄一個(gè)文件 (header 文件或不是) . 如果你將使用Doxygen來輸出文檔 , 那么你最好在這個(gè)標(biāo)簽后面緊接著寫上文件名字 . 它是一個(gè)top level 標(biāo)簽.
• @header: 跟上面的類似 , 但是是在 HeaderDoc中使用 . 當(dāng)你不使用 Doxygen時(shí) , 不要使用上面的標(biāo)簽.
• @author: 用它來寫下這個(gè)文件的創(chuàng)建者信息.
• @copyright: 添加版權(quán)信息.
• @version: 用它來寫下這個(gè)文件的當(dāng)前版本 , 如果在工程生命周期中版本信息有影響時(shí)這會(huì)很重要.

當(dāng)然你還可以使用更多的標(biāo)簽 , 但是這些都是最常使用的一部分 . 我建議你通覽HeaderDoc 或 the Doxygen文檔 , 這樣就可以發(fā)現(xiàn)一些額外的你想使用的關(guān)鍵字.

現(xiàn)在我們來看對(duì)LaunchViewController.h 頭文件添加注釋 . 找到文件的開頭 , 就在import 命令之前 . 在那里添加下面的幾行：

/*!
 *  @header LaunchViewController.h
 *
 *  @brief  啟動(dòng)視圖控制器,在程序啟動(dòng)時(shí)加載顯示
 *
 *  @author LEE
 *  @copyright  ? 2016年 lee. All rights reserved.
 *  @version    16.3.3
 */

你可以把 LEE 替換成你自己的名字或者公司的名字 . 同樣的 , 使用 brief標(biāo)簽而不省略它是很好的習(xí)慣 , 因?yàn)樗鼤?huì)讓文檔系統(tǒng) (在HeaderDoc 和 Doxygen中稍后將會(huì)看到) 在輸出的HTML網(wǎng)頁(yè)上展示你在這兒添加的簡(jiǎn)短描述 . 我再提醒一次 , 在Doxygen里你可以使用反斜杠來代替“@”。同樣的 , 在這里你將不會(huì)看到剛才說的文檔長(zhǎng)什么樣 , 但是我們將會(huì)在后續(xù)輸出HTML文件時(shí)展示.

以上的都很棒 , 但是實(shí)事卻是在大多數(shù)情況下 , 你創(chuàng)建的新文件里由Xcode自動(dòng)添加的提供信息的默認(rèn)注釋都非常好而且夠用了 . 當(dāng)你在團(tuán)隊(duì)里同其他人一起協(xié)作 , 并且每個(gè)成員必須描述清楚他負(fù)責(zé)的那些文件的細(xì)節(jié)信息時(shí) , 或者當(dāng)你打算使用 HeaderDoc 或 Doxygen來輸出一個(gè)工程的完整文檔時(shí) , 又或者當(dāng)你是獨(dú)立開發(fā)者但是工程擁有數(shù)量眾多的文件時(shí) , 你可能想創(chuàng)建一個(gè)文件描述塊 . 不管怎樣 , 由你自己決定你的文檔系統(tǒng)需要完善到哪個(gè)level.

類:

讓我們來看看怎樣對(duì)class或者protocol寫注釋文檔 . 再一次的 , 我只給出最常用的標(biāo)簽 . 自己查看說明文檔了解更多標(biāo)簽信息.

• @class: 用它來指定一個(gè)class的注釋文檔塊的開頭 . 它是一個(gè)top level標(biāo)簽 . 在它后面應(yīng)該給出class名字.
• @interface: 同上.
• @protocol: 同上兩個(gè)一樣 , 只是針對(duì)protocols.
• @superclass: 當(dāng)前class的superclass.
• @classdesign: 用這個(gè)標(biāo)簽來指出你為當(dāng)前class使用的任何特殊設(shè)計(jì)模式 (例如 , 你可以提到這個(gè)class是不是單例模式或者類似其它的模式).
• @coclass: 與當(dāng)前class合作的另外一個(gè)class的名字.
• @helps: 當(dāng)前class幫助的class的名字.
• @helper: 幫助當(dāng)前class的class名字.

實(shí)際上 , 可能除了superclass你幾乎很少用到上面的標(biāo)簽 . 可用標(biāo)簽的列表很長(zhǎng) , 只是我覺得在這里列出更多沒太大意義 . 必須指出的是從superclass開始以及下面的所有標(biāo)簽 , 都不能被 Doxygen識(shí)別 , 只能被HeaderDoc識(shí)別 . 同樣的 , 在Xcode里的 Quick Help 和 Help Popup 彈出框里展示的是各個(gè)標(biāo)簽旁邊的值 , 而不會(huì)展示標(biāo)簽本身 . 因此 , 用不用他們?nèi)Q于你是否使用文檔系統(tǒng)以及使用哪一個(gè).

/*!
 *  @class LaunchViewController
 *
 *  @brief 啟動(dòng)視圖控制器類
 *
 *  @superclass SuperClass: UIViewController
 *  @classdesign    視圖控制器基類
 *  @coclass    AppDelegate
 *  @helps      不幫助其他類
 *  @helper     無幫助類
 */
@interface LaunchViewController : UIViewController

協(xié)議:

按照上面的方法也可以對(duì)protocol添加注釋 . 在LaunchViewController.h 文件開頭添加下面的幾行:

/*!
 *  @protocol ViewControllerDelegate
 *
 *  @brief 啟動(dòng)視圖控制器協(xié)議
 */
@protocol LaunchViewControllerDelegate

/*!
 *  啟動(dòng)視圖控制器已經(jīng)消失
 */
-(void)launchViewControllerDidDisappear;

可以看到在上面 , 我們也聲明了一個(gè)delegate 方法 . 可能此刻你覺得那毫無意義 , 但是我故意把它放在這里是作為示例demo ; 當(dāng)我們使用 HeaderDoc 和 Doxygen 來導(dǎo)出文檔時(shí)就會(huì)在導(dǎo)出的頁(yè)面看到它了.

結(jié)構(gòu)體:

現(xiàn)在我們討論了files,classes 和protocols 希望你有了一個(gè)大概的了解，現(xiàn)在看看一些特殊示例：怎樣對(duì)structs 和 enumerations進(jìn)行注釋。它們的共同點(diǎn)是在兩個(gè)當(dāng)中都使用 @typedef top level 標(biāo)簽，以此來標(biāo)示注釋塊的開始（再次提醒使用top level 完全自愿）。

特別是對(duì)于Doxygen系統(tǒng)，不使用@typedef標(biāo)簽，你應(yīng)該對(duì)structs使用@struct 標(biāo)簽，對(duì)enums使用@enum標(biāo)簽。

讓我們看以下的代碼。把它添加到LaunchViewController.h 文件的interface之前：

typedef struct {

    int type;

    float time;

    BOOL isShowImage;

} LaunchConfig;

現(xiàn)在把下面的注釋添加在它前面:

/*!
 *  @typedef LaunchConfig
 *
 *  @brief  啟動(dòng)設(shè)置.
 *
 *  @discussion 啟動(dòng)視圖控制器會(huì)根據(jù)此結(jié)構(gòu)體內(nèi)的變量值實(shí)現(xiàn)相應(yīng)的操作.
 *
 *  @field launchType 啟動(dòng)類型
 *  @field launchTime  啟動(dòng)視圖控制器顯示時(shí)間
 *  @field isShowImage 是否顯示圖片
 */
typedef struct {

    int launchType;

    float launchTime;

    BOOL isShowImage;

} LaunchConfig;

可以看到 , 出現(xiàn)了一個(gè)名叫 @field 的新標(biāo)簽 . 這個(gè)標(biāo)簽的目的是對(duì)struct里面的每一個(gè)變量進(jìn)行描述 . 再次 , 我必須強(qiáng)調(diào) HeaderDoc 和 Doxygen 的不同之處 . 在 HeaderDoc 里 , 這個(gè)標(biāo)簽是可接受且有效的 . 但是 , 在 Doxygen 里卻不是這樣 . 在這個(gè)案例里我們做的僅僅是分開對(duì)每一個(gè)變量進(jìn)行注釋 . 這樣做會(huì)使當(dāng)我們?cè)?implementation 文件里使用它們時(shí)能展示出每個(gè)的注釋 . 我們來看看吧 (注意標(biāo)簽和變量上方的注釋有著不同的值 , 所以在后面會(huì)更輕松的區(qū)別出來):

/*!
 *  @struct LaunchConfig
 *
 *  @brief  啟動(dòng)設(shè)置.
 *
 *  @discussion 啟動(dòng)視圖控制器會(huì)根據(jù)此結(jié)構(gòu)體內(nèi)的變量值實(shí)現(xiàn)相應(yīng)的操作.
 *
 *  @field launchType 啟動(dòng)類型
 *  @field launchTime  啟動(dòng)視圖控制器顯示時(shí)間
 *  @field isShowImage 是否顯示圖片
 */
typedef struct {

    /*! 啟動(dòng)類型 */
    int launchType;
    
    /*! 啟動(dòng)視圖控制器顯示時(shí)間 */
    float launchTime;

    /*! 是否顯示圖片 */
    BOOL isShowImage;

} LaunchConfig;

如果現(xiàn)在到 LaunchViewController.m 文件中定義一個(gè)這個(gè)struct的變量 , 無論輸入以上任何變量的一個(gè)都會(huì)在彈出窗口里看到它的描述.

Enumerations也是同樣的 , 所以我把它作為練習(xí)留給你自己去創(chuàng)建一個(gè)enum類型然后進(jìn)行注釋 . 非常簡(jiǎn)單 , 是不是 ? 當(dāng)enum創(chuàng)建好后 , 到viewDidLoad方法里去查看它的注釋會(huì)不會(huì)在Xcode的幫助選項(xiàng)里展示出來.

錯(cuò)誤提示

在先前的例子里可以看到 , 在 @param 標(biāo)簽旁必須寫出變量名字 , 之后才是描述信息 . 當(dāng)然 , 誤輸入一個(gè)變量名 , 特別是當(dāng)它有些復(fù)雜時(shí) , 以及創(chuàng)建的文檔包含錯(cuò)誤都是很有可能的 . 但是 , 有個(gè)方法可以避免這種情況發(fā)生 , 我猜你可能并不知道Xcode可以在這時(shí)成為你的可靠助手.

盡管Xcode在文檔開始寫時(shí)就處理了 , 它也可以幫助你避免誤輸入任何變量名 . 只要開啟一個(gè)配置就能讓它做到這點(diǎn) . 讓我們來看看我到底想表達(dá)的是什么:

在 Project Navigator里 , 點(diǎn)擊工程 , 找到Build Settings標(biāo)簽 , 在搜索框里輸入comments關(guān)鍵字然后等待下方給出的結(jié)果 . 其中一個(gè)結(jié)果就是名為Documentation Comments的配置 , 通常它的默認(rèn)值是NO . 你做的僅僅是把它的值設(shè)為YES , 一切就緒 . 如下圖所示:

設(shè)置Documentation Comments為YES

設(shè)置好后 , 我們舉個(gè)例子來演示一下效果.

就拿我們之前的寫好的示例代碼來說 , 我將注釋中 @param 標(biāo)簽后面的參數(shù)名故意寫錯(cuò) , 大家可以看到 Xcode為我們彈出了警告:

注釋參數(shù)名錯(cuò)誤警告

這時(shí)候你點(diǎn)擊黃色的警告三角 , 就會(huì)看到Xcode為你自動(dòng)推薦了正確的變量名 , 你可以繼續(xù)點(diǎn)擊它就會(huì)幫你自動(dòng)修復(fù) , 當(dāng)然你也可以自己去修改.

正確變量名提示

有了上面的這些 , 麻麻再也不需要擔(dān)心在寫文檔時(shí)誤輸入任何變量名了.

總結(jié)

上面說了這么多相信你已經(jīng)對(duì)文檔注釋有了更多的了解 , 想象一下 當(dāng)你在使用別人的庫(kù)做開發(fā)時(shí) , 調(diào)用某些方法 你可能并不知道這個(gè)方法是做什么的 , 但是當(dāng)代碼填充框內(nèi)的注釋出現(xiàn)時(shí) , 是不是心里暗爽呢 ? 因?yàn)槟悴恍枰倩~外的時(shí)間去做了解 , 換位思考 , 當(dāng)別人在使用你的代碼時(shí) , 也可以獲得相同的便利 , 豈不是兩全其美嗎 ?

之前我們有提到兩個(gè)工具 Doxygen 和 HeaderDoc , 其中有一些注釋標(biāo)簽的使用也是根據(jù)這兩個(gè)做了很多說明 . 如果你想繼續(xù)了解注釋文檔的生成 , 那么請(qǐng)繼續(xù)閱讀__注釋文檔 __, 在這里你會(huì)了解到如何使用不同工具來生成屬于自己的注釋文檔.

我是LEE , 如果你還有更好的建議 歡迎給我留言 , 如果喜歡記得點(diǎn)贊喲 ! 么了個(gè)噠~

注: 本篇文章主要參考自AppCoda.