### 前言

對於開發人員而言，文件的作用不言而喻。文件不僅可以提高軟體開發效率，還能便於以後的軟體開發、使用和維護。上一篇主要講述 Objective-C 生成文件，本篇主要講述 Swift 快速生成開發文件工具 [Jazzy](https://github.com/realm/jazzy)。

### 簡介

Jazzy 是 Swift 和 Objective-C 的文件生成工具。Jazzy 並不會解析原始檔，而是使用 AST 來表示程式碼，並且提供準確的結果。Jazzy是一個命令列實用程式, 可以從已編譯的 Swift 模組中生成文件，輸出風格和官方文件匹配。

![jazzy](https://img-blog.csdnimg.cn/67d670a0161440bcb02f10e575e1a5e8.png)

### 執行環境

- 建議在 macOS 上執行
- 支援 Xcode 和 Swift Package Manager 專案

### 安裝

```
sudo gem install jazzy -n /usr/local/bin --verbose
```

![jazzy](https://img-blog.csdnimg.cn/2896d2ef382e4e85abdf97a415ba245f.png)

### 使用

- 終端進入工程目錄

```
 cd /Users/yusheng/Desktop/Jazzy
```

- 執行命令列

```
jazzy --min-acl internal
# 選擇 Swift 語言版本
jazzy --swift-version 4.1.2 --min-acl internal
```

### 常見問題

**1.安裝問題**

```
ERROR: Failed to build gem native extension.

current directory: /Library/Ruby/Gems/2.6.0/gems/redcarpet-3.5.0/ext/redcarpet

/System/Library/Frameworks/Ruby.framework/Versions/2.6/usr/bin/ruby -I /System/Library/Frameworks/Ruby.framework/Versions/2.6/usr/lib/ruby/2.6.0 -r ./siteconf20190906-93824-4j4s2f.rb extconf.rb

mkmf.rb can't find header files for ruby at /System/Library/Frameworks/Ruby.framework/Versions/2.6/usr/lib/ruby/include/ruby.h

You might have to install separate package for the ruby development

environment, ruby-dev or ruby-devel for example.

extconf failed, exit code 1

Gem files will remain installed in /Library/Ruby/Gems/2.6.0/gems/redcarpet-3.5.0 for inspection.

Results logged to /Library/Ruby/Gems/2.6.0/extensions/universal-darwin-19/2.6.0/redcarpet-3.5.0/gem_make.out

```

解決：

```
# 這是由於本地安裝的ruby版本低導致的問題，更新ruby版本即可
brew upgrade ruby
```

**2.安裝問題**

```
Can't find header files / clang
```

執行下命令即可：

```
xcode-select --install
```

**3.安裝問題**

```
dyld: Symbol not found: _$s11SubSequenceSlTl
```

- 更新至 macOS 10.14.4 或更高版本；或者
- 安裝 Xcode 10.2 或更高版本在/Applications/Xcode.app.

**4.執行jazzy命令是問題**

```
xcodebuild: error: The directory does not contain an Xcode project, workspace or package.

...

Please confirm that `xcodebuild` is building a Swift module.
```

將專案編譯下即可執行成功

### 文件生成效果

**[Jazzy 的 Objective-C 文件](https://github.com/realm/jazzy/blob/master/ObjectiveC.md)**

![jazzy](https://img-blog.csdnimg.cn/a04e6e06f28d4ace98127ced83fda4c2.jpeg)
![在這裡插入圖片描述](https://img-blog.csdnimg.cn/5705c2d4a670449ca89661068bf4c12d.jpeg#pic_center)

IOS技術分享| iOS快速生成開發文件（二）

相關文章