33
Help us understand the problem. What are the problem?

More than 5 years have passed since last update.

posted at

updated at

【Swift】ドキュメンテーションコメントで使える Symbol Command Syntax のキーワード【まとめ】

はじめに

API Design Guidelineにて、ドキュメンテーションコメントについて触れられています。

Write a documentation comment for every declaration.

(( ;゚Д゚))

ということで、しっかりドキュメンテーションコメントを書くためにまとめてみました。

基本的には公式リファレンスをしっかり読んでもらえればこの記事を読む必要はないかと思います。笑

公式リファレンスをもとに書きましたが、解釈が間違えている箇所などあればご指摘ください。 :raised_hands:

Symbol Command Syntax とは?

Symbolは、クラスやメソッド、列挙型などを指します。

Symbolのドキュメンテーションコメントとして、Symbol Command Syntaxという書き方で書くことができるようです。

ここでは、Symbol Command Syntaxのキーワードの紹介に留めますので、
ドキュメンテーションコメントの詳しい書き方については触れません。

キーワードの種類

キーワードの種類としてSectionCalloutの2種類があります。
それぞれについてまとめていこうと思います。

Sectionはドキュメンテーションコメントの大項目、Calloutは補助的な項目というイメージです。

Section

Sectionにあたるキーワードは、ParametersReturnsといった、クイックヘルプの左サイドの項目として表示されるものです。

Section一覧

それでは、Sectionのキーワードを紹介します。例や画像はリファレンスのものになります。

Parameter

  • 種類:section
  • 説明:パラメータの説明を書きます。複数のパラメータについて記述する場合は後述のParametersを使用します。

  • 例:

/// - parameter llamaCount: The number of llamas in the managed herd.

MFR_symbol_section_parameter_2x.png

Parameters

  • 種類:section
  • 説明:複数のパラメータの説明を書きます。

  • 例:

/**
  - parameters:
    - cubes: The cubes available for allocation
    - people: The people that require cubes
 */

MFR_symbol_section_parameters_2x.png

Returns

  • 種類:section
  • 説明:Symbolの返り値を書きます。一つのSymbolに複数のReturnsキーワードは書けません。(複数書いた時の挙動は決められていない)

  • 例:

/// - returns: A random number between `min` and `max`

MFR_symbol_section_returns_2x.png

Throws

  • 種類:section
  • 説明:エラーを返すメソッドや関数の場合に投げるエラーを書きます。一つのSymbolに複数のThrowsキーワードは書けません。(複数書いた時の挙動は決められていない)

  • 例:

/// - throws: An error of type `FakeArrayError`

MFR_symbol_section_throws_2x.png

Callout

Calloutは、AuthorVersionなど、Descriptionの項目の中の項目として表示されるものがあたります。

MFR_symbol_description_field_2x.png

Callout一覧

それでは、Calloutも一気に紹介します。

Attention

  • 種類:callout
  • 説明:使用者への注意喚起を書きます。

  • 例:

/**
  An example of using the attention field

  - attention: What I if told you
  you read this line wrong?
 */

MFR_symbol_field_attention_2x.png

Author

  • 種類:callout
  • 説明:宣言の作成者を書きます。複数人いる場合は後述のAuthorsを使います。

  • 例:

/**
  An example of using the author field

  - author: William Shakespeare
 */

MFR_symbol_field_author_2x.png

Authors

  • 種類:callout
  • 説明:宣言の作成者(複数人)を書きます。一人の場合は前述のAuthorを使います。

  • 例:

/**
  An example of using the authors callout

  - authors:
   Plato

   Aristotle

   Other amazing
   classical folk
 */

MFR_symbol_field_authors_2x.png

Bug

  • 種類:callout
  • 説明:バグについて書きます。一つのSymbolに対して複数設置できるので、複数バグがある場合は一つずつ書くこともできます。

  • 例:

/**
  An example of using the bug field

  - bug:
  [*bugExample* contains a memory leak](BugDB://problem/1367823)

  - bug:
  [Passing a `UIViewController` crashes *bugExample*](BugDB://problem/2274610)
 */

MFR_symbol_field_bug_2x.png

Complexity

  • 種類:callout
  • 説明:計算量について書きます。computed propertyでオーダーがO(1)でないものには、このcalloutを記入して利用者に分かるようにします。(プロパティアクセスは一般的にそれほどの計算量を要さないと思われているため)

  • 例:

/**
  An example of using the complexity field

  - complexity:
  The method demonstrates an inefficient way to sort
  using an O(N\*N\*N) (order N-cubed) algorithm
 */

MFR_symbol_field_complexity_2x.png

Copyright

  • 種類:callout
  • 説明:コピーライトを書きます。

  • 例:

/**
  An example of using the copyright field

  - copyright: Copyright © 1215
  by The Group of Barrons
 */

MFR_symbol_field_copyright_2x.png

Date

  • 種類:callout
  • 説明:日付を書きます。一つのSymbolに対して複数書くことができます。

  • 例:

/**
  An example of using the date field

  Last date this example was changed
  - date: August 19, 2015

  Days the method produces special results
  - date: 12/31
  - date: 03/17
 */

MFR_symbol_field_date_2x.png

Experiment

  • 種類:callout
  • 説明:実験内容を書きます。一つのSymbolに対して複数書くことができます。

  • 例:

/**
  An example of using the experiment field

  - experiment: Pass in a string in the present tense
  - experiment: Pass in a string with no vowels
  - experiment:
  Change the third case statement to work only with consonants
 */

MFR_symbol_field_experiment_2x.png

Important

  • 種類:callout
  • 説明:重要事項を書きます。一つのSymbolに対して複数書くことができます。

  • 例:

/**
  An example of using the important field

  - important:
  "The beginning is the most important part of the work."
  \
  –Plato
 */

MFR_symbol_field_important_2x.png

Invariant

  • 種類:callout
  • 説明:不変な内容(実行中にtrueが保証される条件)を書きます。一つのSymbolに対して複数書くことができます。

  • 例:

/**
  An example of using the invariant field

  - invariant:
  The person reference will not change during the execution of this method
 */

MFR_symbol_field_invariant_2x.png

Note

  • 種類:callout
  • 説明:注意事項を書きます。一つのSymbolに対して複数書くことができます。

  • 例:

/**
  An example of using the note field

  - note:
  This method returns an estimate.
  Use `reallyAccurateReading` to get the best results.
  */

MFR_symbol_field_note_2x.png

Precondition

  • 種類:callout
  • 説明:前提条件を書きます。

  • 例:

/**
  An example of using the precondition field

  - precondition: The `person` property must be non-nil.
  - precondition: `updatedAddress` must be a valid address.
 */

MFR_symbol_field_precondition_2x.png

Postcondition

  • 種類:callout
  • 説明:完了時に保証される状態を書きます。

  • 例:

/**
  An example of using the postcondition field

  - postcondition:
  After completing this method the billing address for
  the person will be set to `updatedAddress` if it is valid.
  Otherwise the billing address will not be changed.
 */

MFR_symbol_field_postcondition_2x.png

Remark

  • 種類:callout
  • 説明:備考等を書きます。

  • 例:

/**
  An example of using the remark field

  - remark:
  The performance could be reduced from N-squared to
  N-log-N by switching patterns.
 */

MFR_symbol_field_remark_2x.png

Requires

  • 種類:callout
  • 説明:必要事項を書きます。

  • 例:

/**
  An example of using the requires field

  - requires: `start <= end`.
  - requires: `count > 0`.
 */

MFR_symbol_field_requires_2x.png

SeeAlso

  • 種類:callout
  • 説明:関連情報や参照を書きます。一つのSymbolに対して複数書くことができます。

  • 例:

/**
  An example of using the seealso field

  - seealso:
  [The Swift Standard Library Reference](https://developer.apple.com/library/prerelease/ios//documentation/General/Reference/SwiftStandardLibraryReference/index.html)
 */

MFR_symbol_field_seealso_2x.png

Since

  • 種類:callout
  • 説明:Symbolが利用可能になった時の情報(OS情報やフレームワークのバージョン、日付など)を書きます。一つのSymbolに対して複数書くことができます。

  • 例:

/**
  An example of using the since field

  - since: First available in Mac OS 7
 */

MFR_symbol_field_since_2x.png

Todo

  • 種類:callout
  • 説明:Symbolを完成させるためや更新するためにやるべきことを書きます。一つのSymbolに対して複数書くことができます。

  • 例:

/**
  An example of using the todo field

  - todo: Run code coverage and add tests
 */

MFR_symbol_field_todo_2x.png

Version

  • 種類:callout
  • 説明:バージョン情報を書きます。一つのSymbolに対して複数書くことができます。

  • 例:

/**
  An example of using the version field

  - version: 0.1 (61A329)
 */

MFR_symbol_field_version_2x.png

Warning

  • 種類:callout
  • 説明:警告事項を書きます。一つのSymbolに対して複数書くことができます。

  • 例:

/**
  An example of using the warning field

  - warning:
  Not all code paths for this method have been tested
 */

MFR_symbol_field_warning_2x.png

終わりに

ドキュメンテーションコメントも適切に書いて、誰にでもわかりやすいコードを書きたいですね。

また、書き終えてから見つけたのですが、こちらのスライドにて今回の内容にあたることも含めて、ドキュメンテーションコメントについて丁寧に解説されているので、とても勉強になります。

参考

Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
Sign upLogin
33
Help us understand the problem. What are the problem?