0Pricing
Swift Academy · レッスン

コードのドキュメント化（DocC入門）

DocC コメント（///および/** ... */）を書き、パラメーターと戻り値を dokumentし、例を追加して、SwiftPMパッケージ用の静的ドキュメントを生成します。

「コードのドキュメント化（DocC入門）」はCoddyKit上の無料Swift Academyレッスンです。 これはレッスン3/3です。 下記で完全なレッスンを無料で読むことができます。その後、ブラウザ内の組み込みコードエディタと24時間対応のAIチューターでハンズオン演習できます。 これはSwift Academy学習パスの一部であり、ウェブとCoddyKitアプリ全体で進捗が同期されます。 Swift Academyコースには全3レッスンが含まれています。

DocCとは

DocCを使うと、適切に記述したコメントから閲覧可能なドキュメントサイトを生成できます。

  • ///または/** ... */を使用します
  • 何をするものかを説明し、小さな例を示します
  • パラメータと戻り値をドキュメント化します

関数のドキュメント

宣言のすぐ上に///を記述します。パラメータと戻り値にはリストを使用します。

/// Adds two integers and returns the sum.
/// - Parameters:
///   - a: First addend.
///   - b: Second addend.
/// - Returns: The sum of `a` and `b`.
/// - Remark: Pure function; no side effects.
func sum(_ a: Int, _ b: Int) -> Int { a + b }

print(sum(2, 3)) // 5

型とメンバーのドキュメント

型にはブロックコメント/** ... */が適しています。メンバーには///で短いドキュメントを追加します。

/** A simple counter that tracks a running total.

 Use <code>increment()</code> to add one or a custom amount.
 
 - Note: The type is value-based (a struct).
 */
struct Counter {
    /// Current value of the counter.
    private(set) var value: Int = 0

    /// Increments the counter.
    /// - Parameter amount: How much to add (default is 1).
    mutating func increment(by amount: Int = 1) { value += amount }
}

var c = Counter()
c.increment()
c.increment(by: 3)
print("value =", c.value) // 4

例のセクション

小さな例のセクションを使用します。モバイル画面に収まるよう、サンプルは短くします。

/// Repeats a message a given number of times.
///
/// **Example**
/// ```swift
/// repeatMessage("Hi", times: 2) // prints twice
/// ```
/// - Parameters:
///   - text: Message to print.
///   - times: How many times to print.
func repeatMessage(_ text: String, times: Int) {
    for _ in 0..<times { print(text) }
}

repeatMessage("Hi", times: 2)

ドキュメントをビルドする

SwiftPMまたはXcodeを使用してドキュメントをビルドします。常に最新の状態を保てるよう、ドキュメントはインラインで記述するのがおすすめです。

// Generate documentation for a SwiftPM package (examples):
//   swift package generate-documentation --target MyLib
//   swift package generate-documentation --target MyLib --output-path Docs
//
// Preview in Xcode (DocC):
//   Product > Build Documentation
//
// Tip: keep docs close to code; DocC picks up symbols with /// or /** ... */.

ドキュメントのスタイル

ヒント:

  • 1行の要約から始めます。
  • 内部実装ではなく、何をするかを説明します。
  • 重要な場合にのみエッジケースをドキュメント化します。
  • 長い説明よりも、小さな例を優先します。

DocCコメントの形式

確認: DocCドキュメントを生成するのはどのコメントですか?

まとめ

まとめ: シンボルの上にDocCコメントを記述し、パラメータと戻り値を含め、小さな例を追加してから、SwiftPMまたはXcodeでドキュメントを生成します。

よくある質問

「コードのドキュメント化（DocC入門）」レッスンは無料ですか？

はい。「コードのドキュメント化（DocC入門）」の完全なテキストはこのウェブで無料で読めます。インタラクティブに演習し（組み込みコードエディタと24時間対応のAIチューター）、Swift Academyコースの残りをアンロックするには、CoddyKit PROにアップグレードしてください。 Swift Academyコースには全3レッスンが含まれています。

「コードのドキュメント化（DocC入門）」で何を学びますか？

DocC コメント（///および/** ... */）を書き、パラメーターと戻り値を dokumentし、例を追加して、SwiftPMパッケージ用の静的ドキュメントを生成します。 ブラウザで直接実行するハンズオンコードでSwift Academyを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。

Swift Academyを始めるのに経験は必要ですか？

事前経験は必要ありません。CoddyKitのSwift Academyは初級者から上級者向けに構成されているため、ここから始めるか最初から始めて、自分のペースで進むことができます。 これはレッスン3/3です。

「コードのドキュメント化（DocC入門）」レッスンにはどのくらい時間がかかりますか？

ほとんどのCoddyKitレッスンは約5～10分かかります。各レッスンはコンパクトでインタラクティブなので、着実に進歩し、ウェブとアプリ全体で正確に前回の場所から再開できます。

このSwift Academyレッスンでコードを書いて実行できますか？

はい。すべてのSwift Academyレッスンに組み込みコードエディタが含まれているため、ブラウザでリアルコードを書いて実行し、即座のAIフィードバックを取得できます。ローカル設定は不要です。

このコースのすべてのレッスン

  1. SwiftFormat／SwiftLintの基礎
  2. スタイルガイドとAPI設計ガイドライン
  3. コードのドキュメント化（DocC入門）
← Swift Academyに戻る