Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Features
Speaker Deck
PRO
Sign in
Sign up for free
Search
Search
ど・ち・ら・にしようかな♪ JazzyとDocC
Search
totokit4
July 20, 2022
Programming
0
1.3k
ど・ち・ら・にしようかな♪ JazzyとDocC
https://hey.connpass.com/event/249808/
totokit4
July 20, 2022
Tweet
Share
More Decks by totokit4
See All by totokit4
JAWS-UG20250116_iOSアプリエンジニアがAWSreInventに行ってきた(真面目編)
totokit4
0
240
iOSアプリエンジニアがAWSreInvent行ってきた
totokit4
0
120
re:Inventなんも分からんけどとりあえず全力で行く
totokit4
0
310
カンファレンスを全力で楽しむ技術
totokit4
0
290
デブサミウーマン2023_totokit4
totokit4
5
2k
GitHub Copilotを使って ちょっと楽にUnitTestを書けるようになった
totokit4
2
3.5k
Other Decks in Programming
See All in Programming
20250704_教育事業におけるアジャイルなデータ基盤構築
hanon52_
4
280
エンジニア向け採用ピッチ資料
inusan
0
180
AIエージェントはこう育てる - GitHub Copilot Agentとチームの共進化サイクル
koboriakira
0
480
Composerが「依存解決」のためにどんな工夫をしているか #phpcon
o0h
PRO
1
250
CursorはMCPを使った方が良いぞ
taigakono
1
220
『自分のデータだけ見せたい!』を叶える──Laravel × Casbin で複雑権限をスッキリ解きほぐす 25 分
akitotsukahara
1
600
What Spring Developers Should Know About Jakarta EE
ivargrimstad
0
380
すべてのコンテキストを、 ユーザー価値に変える
applism118
2
1.1k
AI時代のソフトウェア開発を考える(2025/07版) / Agentic Software Engineering Findy 2025-07 Edition
twada
PRO
23
2.5k
Flutterで備える!Accessibility Nutrition Labels完全ガイド
yuukiw00w
0
140
AIコーディング道場勉強会#2 君(エンジニア)たちはどう生きるか
misakiotb
1
280
なんとなくわかった気になるブロックテーマ入門/contents.nagoya 2025 6.28
chiilog
1
260
Featured
See All Featured
Done Done
chrislema
184
16k
Building Applications with DynamoDB
mza
95
6.5k
The Myth of the Modular Monolith - Day 2 Keynote - Rails World 2024
eileencodes
26
2.9k
Java REST API Framework Comparison - PWX 2021
mraible
31
8.7k
Designing Dashboards & Data Visualisations in Web Apps
destraynor
231
53k
Helping Users Find Their Own Way: Creating Modern Search Experiences
danielanewman
29
2.7k
Building a Scalable Design System with Sketch
lauravandoore
462
33k
What's in a price? How to price your products and services
michaelherold
246
12k
RailsConf 2023
tenderlove
30
1.1k
How to Create Impact in a Changing Tech Landscape [PerfNow 2023]
tammyeverts
53
2.8k
Docker and Python
trallard
44
3.5k
Gamification - CAS2011
davidbonilla
81
5.3k
Transcript
ど・ち・ら・にしようかな♪ JazzyとDocC
自己紹介 とと @totokit4(Twitter) 2021.9 hey入社 のiOSエンジニア 関西出身 めっちゃ緊張してるので みんなリアクションしてね! #voicy_hey
お店のキャッシュレスを かんたんに クレジットカード決済も、電子マネー決済も、 QR決済も、これひとつで。
iOS SDKのドキュメントを 自動生成したい!!
目次 1 2 3 4 背景と目的 まずは、Jazzy触ってみた 次に、DocC触ってみた STORES 決済
での運用方法
ドキュメント自動生成ツールって何よ 0
ドキュメント自動生成ツール プログラムコードの中に書いた ドキュメントコメント こんな関数があるよ! このクラスは こういう役割だよ! 引数はこれ! 戻り値はこうだよ〜 プロパティとして これが公開されてるよ〜
HTML Markdown
ドキュメント自動生成ツール と、いうのを Swiftのプログラミングコードで やってくれるのが
背景と目的 1 あらためまして
目的 STORES 決済 SDK コア機能をSDKとして切り出して 他社のPOSアプリにも提供しています
目的 STORES 決済 SDKを組み込む人向けに APIドキュメントを展開しています …… …… が!!!
背景 先日、 Objective-CからSwift化が完了
背景 Objective-C版のSDK でドキュメント生成に使用していた doxygenがSwiftに対応しておらず、 乗り換える必要がありました
背景 オープンソースとして歴史が長く、信頼のある Jazzy、 最近発表された、何と言ってもApple純正!の DocC。 候補はこの2つ! どっちにするか調査を開始しました
まずは、Jazzy触ってみた 2
Jazzy • Realmが提供している Swift / Objective-Cに対 応しているドキュメント生成ツール • 少なくとも2014年からオープンソースで開発され ている
• 公式資料は英語 ◦ 導入事例等の記事が日本語で上がっている • Issueで質問を投げてみたら1日以内に返信がきた
Jazzy触ってみた • コマンドを2つターミナルに叩くだけ ◦ `gem install jazzy` でインストール ◦ `jazzy`
でドキュメント生成
できたもの
Jazzy触ってみた • 各種設定は、コマンドオプションをつけるか • jazzy.yamlを作成して設定を変更 ◦ jazzy.yamlを作ってしまえば、変更はほぼここにしか入らない つけられるオプションの数が すごく多い! 細かく設定するならこっち
操作は基本CUI 導入事例が多いので ネットに情報が多い
Jazzy苦戦したこと 1. 「jazzy」で検索すると“ジャズっぽい雰囲気をあらわす言葉。 ”が出る ◦ ちゃうねん。 ◦ 「jazzy swift」とかで検索しよう 2.
xcodebuild-argumentsの設定むずい!! ◦ ターゲット、ビルドディレクトリ、アーキテクチャ等々複雑なプロジェクトだとなかなか上手くいかない ▪ が、これはjazzyのせいではない ◦ Xcodeの環境変数が使えず、右往左往 3. オプションについては、README1ページを地道に読むしかない! ◦ どれ使うねん。何があんねん。 ◦ 地道にドキュメントを読んで、自分のチームに必要な設定をつける ◦ 公式ドキュメントの親切さレベルはDocCの方が勝つ……気がする
次に、DocC触ってみた 3
DocC • Appleから2021年6月にWWDC21で発表 • 2021年10月にオープンソースになった • Xcode 13以降で利用可能 • 公式ドキュメントは英語のみ
◦ 技術書典で売っていた本で公式ドキュメン トにある情報をほぼ網羅した日本語本が 売っていた Swift-DocCでドキュメントをつくる: Type D4 Lab
DocC触ってみた • Xcodeで全て完結 ◦ 設定、ドキュメントの生成までXcodeぽちぽちで完結
できたもの
DocC触ってみた • Xcodeでビルドするたびにドキュメントを生成するというような設定 ができる • 概念を説明したり、タスクを説明したりするための記事を追加できる • フレームワークの使い方を説明するチュートリアルが作れる • 追加する画像をライトモード用やダークモード用で設定できる
とにかくXcodeとの互換性が最高 操作はGUIでOK 見た目がApple Developer Documentationライクだったりと おしゃんなApple風にこだわるなら こっち
DocC苦戦したこと 1. ドキュメント、 英語しかない。導入事例少ない。 ◦ 何となく分かったつもりやけど、合ってるか自信ないわ… ◦ 出来ることを自分が網羅的に把握できたのか自信ないわ… ▪ 後からSwift-DocCでドキュメントをつくる
を見つけました 2. GUIだから、どこからミスったのか全然分からない ◦ なんか失敗したな、と思ったら1からやり直し 3. Documentation.md、独自ルールを覚えねばならない ◦ README的な役割かと思いきや、設定ファイル的なポジションも ◦ この設定をするのにこのファイルのどこを触らなくちゃいけないのかということの把握が必要
STORES 決済 での運用方法 4
©hey, Inc Jazzy DocC Objective-Cのドキュメント化 ◦ × privateな関数等のドキュメント化 ◦
× ドキュメント化するファイルを指定 ◦ × チュートリアル等の作成 × ◦ 多言語対応 × ×
採用したのは doxygenで出来ていた、多言語対応はどちらでも実現できず。
採用したのは • Jazzyだと出力する内容のコントロールが細かくできる • Jazzyは SwiftのPublicになっているものでも `/// :nodoc:` コメントつけると出力されない ◦
社内で展開する分にはDocCでも良さそう Jazzyを採用
実装と運用 • ワークフローが動いたらドキュメントをzipで吐き出す • ドキュメントバージョンも 勝手にアプリバージョンに合わせてほしい
実装 1. jazzy.yamlファイルを用意 ◦ ここではmodule_version指定以外の設定を定義する 2. Gemfileにjazzyを追加 3. Fastfileにバージョン取得とJazzyを動かす処理をするlaneを追加 4.
BitriseのStepに `bundle install`のスクリプトを追加 5. 作ったlaneを動かすスクリプトを追加 6. 出力したドキュメントをzip化
運用 SDKをリリース時に動くワークフローに組み込んでおけば バージョンアップのたびにドキュメントが CI上で生成! ドキュメントのアップロードまで自動化したいのですが それはまだ検討中。現状は手動です
できたもの できたドキュメントは 無事、公開中!😉 https://stores-payments-sdk.coiney.com/ios/
おしまい
実装 Create Apple's documentation Stepが用意されていたが、 指定できるパラメータが少ないため 使用しませんでした • xcodebuild-argumentsの設定が細かく設定できない •
バージョン固定してしまう
`/// :nodoc:` コメントについて コメントをつけなくても、公開されているAPIは DocCでもJazzyでも、ドキュメントは生成されてしまう
`/// :nodoc:` コメント について ドキュメントが生成されなくなる!!
ダイアグラムスタイル テキスト テキスト テキス ト テキス ト テキスト テキス ト
テキスト テキスト テキスト テキスト テキスト テキス ト テキス ト テキスト テキス ト テキスト テキスト テキスト テキスト テキスト テキス ト テキス ト テキスト テキス ト テキスト テキスト テキスト A. ライン B. ライトトーン C. ダークトーン コネクタ
スタンプ
スタンプ