【Xcode】關閉 Xcode 文件註解的警告 / Warning

	Xcode 在編譯過程中，如果註解的形式是寫成自動文件生成格式，那麼會順便檢查文件註解並且將有問題的部分以 warning 的方法提出。然而這個設計對於使用第三方 framework 的 header 檔時，卻會造成不必要的與過多的警告訊息。

 

問題範例

---

在近期使用的 SDK 中，當宣告 include 如下：

  #include <i1d3SDK.h>

在編譯時 Xcode 則會出現底下的 warning：

進去檔案檢視，出問題的部分如下：

/*****************************************************************************/
/** 	\fn i1d3Status_t i1d3SetCalibrationFromFile (i1d3Handle devHndl, unsigned char *EDRFileName)
*		\brief Calculate calibration matrix from spectral data within an EDR file.
*		\param devHndl handle to the device returned from i1d3GetDeviceHandle()
*		\param *EDRFileName Fully-qualified path to the file.
*
*		Spectral data is read from a monitor-specific EDR file and used to calculate
*		the matrix to be used for measurement purposes.
*/
/*****************************************************************************
PDEC i1d3Status_t i1d3SetCalibrationFromFile (i1d3Handle devHndl, unsigned char *EDRFileName);

警告的位置指到第五行註解內的的 *EDRFileName，與程式邏輯無關，該註解用來自動生成說明文件。由於註解的文件描述宣告在函式之前，導致 Xcode 的文件檢查認為是錯的，並進一步地造成 log 內一堆警告，造成閱讀和觀感上的不佳。

 

避免方法

---

只要在引用的檔頭之前，宣告如下，即可使 Xcode 忽略該檔頭對於文件說明的檢查。

  #pragma clang diagnostic push
  #pragma clang diagnostic ignored "-Wdocumentation"
  #include <i1d3SDK.h>
  #pragma clang diagnostic pop

 

參考資料

---

1. Disable "Documentation Comments" warning for selected files，stackoverflow，2015