Swiftのソースにドキュメントコメントを入れる話

公開日:2019-01-26
最終更新:2019-01-26

はじめに

Objective-Cでコードを書く時にはdoxygen形式でコメントを入れていた。
そうするとクラスやメソッドの概要などがXcodeのQuick Helpへ反映され、便利だなと思っていたのだが。
Swiftで同様にコメントを入れたところ、それがQuick Helpに反映されない・・・
ので、そのことについて調べてみた。


結論

Swiftではdoxygen形式でコメントを書いても、Quick Helpへは一部反映されない。
/3つで始まるコメントを使うと反映される。


どういうことなのか

doxygen形式でも、クラスやコメントのSummaryは正しく認識されるし、ツールを使ってドキュメントを吐き出すことも可能らしい。
しかし、

一行目にメソッドの説明と:param:、:return:を使えばとりあえず問題なし

との情報を見て試したが、:param:がDiscussionの欄に反映され、Parametersの欄にはNo descriptionと表示されてしまう。どうやらObjective-Cのソースのようには認識してくれないようだ。

Option+Command+/を押すと/3つから始まるコメントが自動生成され、この内容はQuick Helpに反映される。

/// <#Description#>  
///  
/// - Parameter param1: <#param1 description#>  
/// - Returns: <#return value description#>

ショートカットですぐ定型のコメントが出るので、doxygen形式よりも便利だなと思った。
あと、Markdown形式で書けるのも良い。
今後Swiftではこの形式のコメントを使っていこうと思う。


参考にしたページ:

記事が少しでもいいなと思ったらクラップを送ってみよう!
18
+1
@marshmallow444の技術ブログ

よく一緒に読まれている記事

0件のコメント

ブログ開設 or ログイン してコメントを送ってみよう
目次をみる

技術ブログをはじめよう

Qrunch(クランチ)は、ITエンジニアリングに携わる全ての人のための技術ブログプラットフォームです。

技術ブログを開設する

Qrunchでアウトプットをはじめよう

Qrunch(クランチ)は、ITエンジニアリングに携わる全ての人のための技術ブログプラットフォームです。

Markdownで書ける

ログ機能でアウトプットを加速

デザインのカスタマイズが可能

技術ブログ開設

ここから先はアカウント(ブログ)開設が必要です

英数字4文字以上
.qrunch.io
英数字6文字以上
ログインする