XCode 11.1 日本語化計画：Markup Formatting Reference

クイックヘルプの構文

マークアップを使用して、Swift コード内の任意のシンボルのリッチ形式のクイックヘルプを作成します。シンボルには、名前付きクラス、メソッドと関数、列挙型、およびその他の名前付きコンストラクトが含まれます。Swift の名前付きコンストラクトの詳細については、Swift プログラミング言語 (Swift 2.2) の宣言を参照してください。

Xcode のクイックヘルプ

Option キーを押しながらシンボルをクリックすると、シンボルのクイックヘルプが表示されます。挿入ポイントがシンボル内にある場合、ユーティリティ領域のクイックヘルプインスペクターにも表示されます。シンボル情報は、説明 や パラメータ などのセクションに分類されます。説明のセクションには、バージョンなどの情報の呼び出しを含めることができます。以下の図は、coreFields 関数のクイックヘルプポップアップとクイックヘルプインスペクターペインを示しています。

クイックヘルプセクション

クイックヘルプの内容は、メソッドのパラメータなどの関連情報の名前付きセクションにグループ化されます。以下の説明が、マークアップ区切り文字を使用して追加されます。

• Description (説明) セクションには、メソッドの目的などの、シンボルの説明が記載されています。


• Parameters (パラメータ) セクションには、メソッドまたは関数のパラメータが一覧表示されます。


• Throws (スロー) セクションには、メソッドまたは関数によって throw されたエラーが記載されています。


• Returns (戻り値) セクションには、メソッドまたは関数の戻り値が記載されています。

パラメータ、スロー、およびリターンセクションは、特定のマークアップ区切り文字を使用して追加されます。

Description (説明) セクション

Description (説明) セクションは、別のセクションの区切り文字の一部ではないマークアップの行で構成されます。 Description (説明) の一部は、セクションの区切り文字の前後に表示できます。Description (説明) セクションのレンダリングされた内容の順序は、マークアップに表示される順序と同じです。

たとえば、以下のマークアップは、図 5-1 に示す説明セクションをレンダリングします。

 1    /**
 2      Errors thrown by fakeArray.
 3
 4      *Values*
 5
 6      `NegativeCount` The count is less than 0.
 7
 8      `EmptyString1` The first string argument is empty.
 9
10      `EmptyString2` The second string argument is empty.
11
12      - Author:
13        Newbie
14      - Version:
15        0.1
16     */
17
18    enum FakeArrayError: ErrorType {…

図 6-1 クイックヘルプ内のセクション

パラメータのセクション

Parameter(パラメータ) と Parameters(パラメータ) の区切り記号を使用して、パラメータのセクションをクイックヘルプに追加します。シンボルのマークアップで両方が区切り文字を使用している場合、クイックヘルプにはすべてのパラメータエントリが表示され、その後にすべてのパラメータエントリが表示されます。パラメータの順序は、マークアップに表示される順序と同じです。

Return (戻り値) のセクション

Returns(応答) 区切り文字を使用して、戻り値のセクションをクイックヘルプに追加します。

Throws (スロー) セクション

Throws(スロー) 区切り文字を使用して、クイックヘルプに Throws (スロー) セクションを追加します。

コールアウトの追加

マークアップには、著者、必要な前提条件、警告など、Swift のシンボルに関する有用な情報を追加する多くのコールアウトの区切り文字が含まれています。コールアウトの内容は、クイックヘルプ内のシンボルの説明セクションに表示されます。

たとえば、以下のマークアップは Important(重要な) コールアウトと Version(バージョン) コールアウトを追加し、図 5-2 に示すクイックヘルプになります。Important のコールアウトは 2 行目から始まります。version コールアウトは、Returns セクションのコールアウトの後、11 行目です。

 1    /**
 2      *A description field*
 3      - important: This is
 4        a way to get the
 5        readers attention for
 6        something.
 7
 8      - returns: Nothing
 9
10      *Another description field*
11      - version: 1.0
12     */

図 5-2 クイックヘルプ内のコールアウト

前：マークアップの文法 次：単一行のコメント

マークアップの本質

マークアップの使用

マークアップ用のコメントマーカー

一行のテキストの構成

複数行のテキストの構成

文字のスパンの構文

リンクの挿入

アセットの挿入

コールアウトの挿入

Escaping Special Characters (特別な文字のエスケープ)

改訂履歴