【DocC】CodeディテクティブのAPIリファレンスを読む

この記事は何？

DocCドキュメントを作成するための@Codeディレクティブについて、Apple開発者向けドキュメントを読む。

ディレクティブの階層

Tutorialページ

• Tutorial
  • XcodeRequirement
  • Intro
    • Image
    • Video
  • Section
    • ContentAndMedia
    • Steps
      • Step
        • Code（←これ）
          • Image
        • Image
        • Video
    • Stack
      • ContentAndMedia
        • Image
        • Video
  • Image
  • Assessments
    • MultipleChoice
      • Choice
        • Justification
        • Image

Codeディレクティブとは

チュートリアルページに表示する、個々のステップで追加するコードを定義する。

パラメータ

• name
  ステップを実行するときにプロジェクトで編集するSwiftコードのファイル名と拡張子。ステップのコードの上に表示される。
• file
  ドキュメントカタログ内にあるSwiftファイル名と拡張子。コードは、チュートリアルページで関連するステップの横に表示される。
• previousFile（指定は任意）
  ドキュメントカタログ内にある、前ステップのコードのSwiftファイル名と拡張子。DocCは「現在のステップのコード」と比較するためにこのファイルを使用する。そのため、読者は「何が変更されたか」を確認できる。デフォルトではDocCは差分について、現在のステップと前のステップのコードを自動的に比較する。このパラメータは、デフォルトの比較対象を上書きして、別のファイルを指定する場合にのみ値を使用する。
• reset（指定は任意）
  前のステップのコードとの比較を無効にしたい場合、このパラメータにtrueを指定する。

概要

@Codeディレクティブは、チュートリアルページにおいて、読者が到達したステップにコードを表示する。

チュートリアルページにおけるステップのスクリーンショット。ステップのテキストが左側に、コード入力した結果のプレビューが右側に表示されている。

コードリストは .swift ファイルに記述する。
すべてのコードファイルを含むコードベースのチュートリアル用フォルダを作成して、管理することが望ましい。
また、探したり参照しやすくするためにファイルの命名規則を考案すべき。
例: [TutorialNameOrNumber]-[SectionNumber]-[StepNumber]-[DescriptiveName].swift

@Codeディレクティブでは、表示したいコードのファイル名と拡張子をfileパラメータに指定する。
チュートリアルを作成すると、DocCはコードを抽出し、チュートリアルページに表示する。

nameパラメータには、ステップで作業する読者が「自分のプロジェクトで編集する際のSwiftファイル名」を指定する。
このファイル名前は、コードリストの上に表示される。

@Imageディレクティブを追加すると、ステップを行った後に読者が見る結果のプレビューを表示できる。

@Tutorial(time: 30) {
    ...
    
    @Section(title: "Add a customization view") {        
        ...
        
        @Steps {
            ...

            @Step {
                Add the `sloth` parameter to initialize the `CustomizedSlothView` in the preview provider, and pass a new `Sloth` instance for the value.
                
                @Code(name: "CustomizedSlothView.swift", file: "01-creating-code-02-07.swift") {
                    @Image(source: "preview-01-creating-code-02-07.png", alt: "A portrait of a generic sloth displayed in the center of the canvas.")
                }
            }

            @Step {
                Set the preview provider sloth's `name` to `"Super Sloth"`, `color` to `.blue`, and `power` to `.ice`.
                
                @Code(name: "CustomizedSlothView.swift", file: "01-creating-code-02-08.swift") {
                    @Image(source: "preview-01-creating-code-02-08.png", alt: "A portrait of an ice sloth on top, followed by four power icons below. The power icons, clockwise from top left, include: ice, fire, wind, and lightning. The ice icon is selected.")
                }    
            
                ...
            }
        }
    }
}

ステップ間の差分を示す

DocCはチュートリアルページにおいて、各ステップで前ステップのコードを自動的に比較し、差分を強調して読者に「自分のコードで何を変更すべきか」を知らせることができる。
この自動比較は、セクションの最初のステップでは行われない。
previousFileパラメータに「DocCが比較するファイル」を指定することで、任意のステップのコードとの比較を強制したり、上書きしたりできる。
差分を表示したくない場合はresetパラメータにtrueを指定する。

子にできる要素

• @Image
  ステップを行った結果のプレビューとなる画像。

親になれる要素

• @Step