[docs] 公開 API に DocC コメントとモジュール概要カタログを追加

- 全 public 型/プロトコル/メンバへ DocC コメント(///)を整備
- PhotoScrubberKit.docc に Overview と Topics グルーピングを追加
- docbuild 警告ゼロを確認

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: shsw228

Sources/PhotoScrubberKit/CustomScrubView.swift

@@ -1,13 +1,24 @@
 import UIKit
 
+/// スクラブのスクロール方向。
 public enum ScrubAxis: Sendable {
+    /// 横方向にページング／スクロールする。
     case horizontal
+    /// 縦方向にページング／スクロールする。
     case vertical
 }
 
+/// メイン画像用の paging スクラブビュー。
+///
+/// `UICollectionView` ベースで 1 ページ = 1 item を全面表示する。スクロールに応じて
+/// ``progress`` を更新し、``CustomScrubViewDelegate`` へ進行度・ページ変化を通知する。
+/// 回転で bounds が変わっても表示ページを保持する。
+///
+/// 単体でも使えるが、サムネイル帯と連動させるなら ``PhotoScrubberCoupling`` を使う。
 @MainActor
 public final class CustomScrubView: UICollectionView {
 
+    /// スクロール方向。変更すると先頭ページへリセットされる。既定は ``ScrubAxis/horizontal``。
     public var axis: ScrubAxis = .horizontal {
         didSet {
             guard oldValue != axis else { return }
@@ -20,12 +31,17 @@ public final class CustomScrubView: UICollectionView {
         }
     }
 
+    /// ページ数と各ページの view を供給するデータソース。
     public weak var pageDataSource: (any CustomScrubViewDataSource)?
+    /// 進行度・表示ページ変化の通知先。
     public weak var pageDelegate: (any CustomScrubViewDelegate)?
 
+    /// 現在の進行度。`0...(pageCount - 1)` の連続値。KVO 可能 (`@objc dynamic`)。
     @objc dynamic public private(set) var progress: CGFloat = 0
+    /// 現在表示中のページ index。
     public private(set) var currentPageIndex: Int = 0
 
+    /// 現在表示中ページにホストされている view。該当が無ければ `nil`。
     public var visibleView: UIView? {
         guard itemCount > 0 else { return nil }
         let indexPath = IndexPath(item: currentPageIndex, section: 0)
@@ -61,6 +77,7 @@ public final class CustomScrubView: UICollectionView {
         register(PageCell.self, forCellWithReuseIdentifier: PageCell.reuseID)
     }
 
+    /// データソースを読み直し、先頭ページへリセットする。
     public override func reloadData() {
         itemCount = pageDataSource?.numberOfPages(in: self) ?? 0
         currentPageIndex = 0
@@ -69,6 +86,10 @@ public final class CustomScrubView: UICollectionView {
         super.reloadData()
     }
 
+    /// 指定ページへ移動する。
+    /// - Parameters:
+    ///   - index: 移動先ページ index。範囲外なら無視される。
+    ///   - animated: アニメーション付きで移動するか。
     public func setCurrentPage(_ index: Int, animated: Bool) {
         guard index >= 0, index < itemCount else { return }
         let extent = pageExtent
@@ -80,6 +101,10 @@ public final class CustomScrubView: UICollectionView {
         updateCurrentPage(to: index)
     }
 
+    /// 進行度を直接指定して位置を合わせる。主に連動相手からの同期に使う。
+    /// - Parameters:
+    ///   - progress: `0...(pageCount - 1)` の連続値。範囲外は丸められる。
+    ///   - animated: アニメーション付きで移動するか。既定 `false`。
     public func setProgress(_ progress: CGFloat, animated: Bool = false) {
         guard itemCount > 0 else { return }
         let extent = pageExtent
@@ -100,12 +125,17 @@ public final class CustomScrubView: UICollectionView {
         pageDelegate?.scrubView(self, didChangeVisiblePage: index)
     }
 
+    /// 末尾にページを 1 つ追加する。追加分の view は ``pageDataSource`` から取得される。
     public func appendPage() {
         itemCount += 1
         let indexPath = IndexPath(item: itemCount - 1, section: 0)
         insertItems(at: [indexPath])
     }
 
+    /// 指定ページを削除し、必要なら表示ページを補正する。
+    /// - Parameters:
+    ///   - index: 削除するページ index。範囲外なら無視される。
+    ///   - animated: アニメーション付きで削除するか。`true` の場合は完了まで `await` で待つ。
     public func deletePage(at index: Int, animated: Bool) async {
         guard index >= 0, index < itemCount else { return }
         let oldCurrent = currentPageIndex

Sources/PhotoScrubberKit/CustomScrubViewController.swift

@@ -1,9 +1,16 @@
 import UIKit
 
+/// ``CustomScrubView`` を `view` 全体に敷いた、メイン単体用のコンテナ ViewController。
+///
+/// サムネイル帯との連動が不要で、メインのスクラブビューだけを画面に置きたいときに使う。
+/// サムネイル連動が必要なら ``PhotoScrubberCoupling`` を使う。
 open class CustomScrubViewController: UIViewController {
 
+    /// 管理対象のスクラブビュー。`viewDidLoad` で `view` に敷き込まれる。
     public let scrubView: CustomScrubView
 
+    /// 指定したスクロール軸でコンテナを生成する。
+    /// - Parameter axis: スクラブの方向。既定は ``ScrubAxis/horizontal``。
     public init(axis: ScrubAxis = .horizontal) {
         self.scrubView = CustomScrubView()
         super.init(nibName: nil, bundle: nil)

Sources/PhotoScrubberKit/CustomScrubViewDataSource.swift

@@ -1,7 +1,13 @@
 import UIKit
 
+/// ``CustomScrubView`` にページ数と各ページの view を供給するデータソース。
+///
+/// ``PhotoScrubberCoupling`` 経由で使う場合は、代わりに
+/// ``PhotoScrubberDataSource`` を実装する（本 protocol は内部で橋渡しされる）。
 @MainActor
 public protocol CustomScrubViewDataSource: AnyObject {
+    /// ページ総数。
     func numberOfPages(in scrubView: CustomScrubView) -> Int
+    /// `index` 番目のページに表示する view を返す。
     func scrubView(_ scrubView: CustomScrubView, viewForPageAt index: Int) -> UIView
 }

Sources/PhotoScrubberKit/CustomScrubViewDelegate.swift

@@ -1,8 +1,11 @@
 import UIKit
 
+/// ``CustomScrubView`` の進行度・表示ページ変化を受け取るデリゲート。全メソッドが任意実装。
 @MainActor
 public protocol CustomScrubViewDelegate: AnyObject {
+    /// スクロールで進行度が変化したとき呼ばれる。`progress` は `0...(pageCount - 1)` の連続値。
     func scrubView(_ scrubView: CustomScrubView, didUpdateProgress progress: CGFloat)
+    /// 表示中のページが別の index に切り替わったとき呼ばれる。
     func scrubView(_ scrubView: CustomScrubView, didChangeVisiblePage index: Int)
 }
 

Sources/PhotoScrubberKit/PhotoScrubberCoupling.swift

@@ -1,15 +1,28 @@
 import UIKit
 
+/// ``PhotoScrubberCoupling`` にメイン画像／サムネイル両方のコンテンツを供給するデータソース。
+///
+/// メイン (``PhotoScrubberCoupling/scrubView``) とストリップ
+/// (``PhotoScrubberCoupling/stripView``) は同じ item 数を共有する。両ビューの
+/// `index` は常に同じ item を指す。
 @MainActor
 public protocol PhotoScrubberDataSource: AnyObject {
+    /// スクラバーが表示する item 数。メイン・サムネイルで共通。
     func numberOfItems(in coupling: PhotoScrubberCoupling) -> Int
+    /// メイン (paging) 側の `index` 番目に表示する view を返す。
     func photoScrubber(_ coupling: PhotoScrubberCoupling, mainViewAt index: Int) -> UIView
+    /// サムネイル帯の `index` 番目に表示する view を返す。
     func photoScrubber(_ coupling: PhotoScrubberCoupling, thumbnailViewAt index: Int) -> UIView
 }
 
+/// スクラブ操作の進行・表示 item 変化を受け取るデリゲート。全メソッドが任意実装。
 @MainActor
 public protocol PhotoScrubberDelegate: AnyObject {
+    /// メイン／ストリップいずれかのスクロールで進行度が変化したとき呼ばれる。
+    ///
+    /// `progress` は `0...(itemCount - 1)` の連続値（item index の小数表現）。
     func photoScrubber(_ coupling: PhotoScrubberCoupling, didUpdateProgress progress: CGFloat)
+    /// 表示中の item が別の index に切り替わったとき呼ばれる。
     func photoScrubber(_ coupling: PhotoScrubberCoupling, didChangeVisibleItem index: Int)
 }
 
@@ -18,25 +31,46 @@ public extension PhotoScrubberDelegate {
     func photoScrubber(_ coupling: PhotoScrubberCoupling, didChangeVisibleItem index: Int) {}
 }
 
+/// Apple Photos.app 風スクラバーの中核。メイン画像ビューとサムネイル帯を双方向に連動させる。
+///
+/// 一方をスクラブするともう一方が追従する。レイアウト（2 ビューの配置）は呼び出し側の責務で、
+/// 本クラスは ``scrubView`` / ``stripView`` の 2 つの `UIView` と結合ロジックだけを提供する。
+///
+/// ## 使い方
+/// 1. ``dataSource`` を設定し、必要なら ``delegate`` / ``prefetcher`` も設定する。
+/// 2. ``scrubView`` と ``stripView`` を任意のレイアウトに配置する。
+/// 3. ``reloadData()`` を呼ぶ。
+///
+/// データ変更は ``appendItem()`` / ``deleteItem(at:animated:)`` で両ビューへ一括反映される。
 @MainActor
 public final class PhotoScrubberCoupling {
 
+    /// メイン (paging) のスクラブビュー。
     public let scrubView: CustomScrubView
+    /// サムネイル帯のストリップビュー。
     public let stripView: ScrubberStripView
 
+    /// item 数とメイン／サムネイル view を供給するデータソース。
     public weak var dataSource: (any PhotoScrubberDataSource)?
+    /// 進行度・表示 item 変化の通知先（任意）。
     public weak var delegate: (any PhotoScrubberDelegate)?
+    /// 周辺 item の事前ロード依頼先（任意）。
     public weak var prefetcher: (any PhotoScrubberPrefetching)?
 
-    /// `didChangeVisibleItem` 発火時に現在 index ± `mainPrefetchRadius` を main 用 prefetch として通知。
+    /// `didChangeVisibleItem` 発火時に現在 index ± `mainPrefetchRadius` を main 用 prefetch として通知。既定 `2`。
     public var mainPrefetchRadius: Int = 2
 
-    /// 同上、thumbnail 用。
+    /// 同上、thumbnail 用。既定 `5`。
     public var thumbnailPrefetchRadius: Int = 5
 
     private let forwardingProxy = ForwardingProxy()
     private var isProgrammaticUpdate = false
 
+    /// スクラバーを生成する。
+    ///
+    /// - Parameters:
+    ///   - scrubView: 既存のメインビューを使う場合に指定。`nil` なら内部で生成する。
+    ///   - stripView: 既存のストリップビューを使う場合に指定。`nil` なら内部で生成する。
     public init(scrubView: CustomScrubView? = nil,
                 stripView: ScrubberStripView? = nil) {
         self.scrubView = scrubView ?? CustomScrubView()
@@ -48,11 +82,18 @@ public final class PhotoScrubberCoupling {
         self.stripView.stripDelegate = forwardingProxy
     }
 
+    /// データソースを読み直し、メイン・サムネイル両方を再構築する。
     public func reloadData() {
         scrubView.reloadData()
         stripView.reloadData()
     }
 
+    /// 指定 index の item をメイン・サムネイル両方から削除する。
+    ///
+    /// 両ビューの削除を並行実行し、完了まで待つ。`async` なので呼び出し側で `await` する。
+    /// - Parameters:
+    ///   - index: 削除する item の index。
+    ///   - animated: アニメーション付きで削除するか。
     public func deleteItem(at index: Int, animated: Bool) async {
         isProgrammaticUpdate = true
         async let mainDone: Void = scrubView.deletePage(at: index, animated: animated)
@@ -61,6 +102,10 @@ public final class PhotoScrubberCoupling {
         isProgrammaticUpdate = false
     }
 
+    /// 末尾に item を 1 つ追加し、メイン・サムネイル両方へ反映する。
+    ///
+    /// 追加後の item は ``dataSource`` から取得されるため、本メソッド呼び出し前に
+    /// データソース側の件数を増やしておくこと。
     public func appendItem() {
         scrubView.appendPage()
         stripView.appendThumbnail()

Sources/PhotoScrubberKit/PhotoScrubberKit.docc/PhotoScrubberKit.md

@@ -0,0 +1,51 @@
+# ``PhotoScrubberKit``
+
+UIKit 製の Apple Photos.app 風スクラバー UI（メイン画像 + サムネイル帯の双方向連動）を提供する Swift Package。
+
+## Overview
+
+レイアウト（2 ビューの配置）は呼び出し側の責務で、ライブラリは 2 つの `UIView` と
+結合ロジックだけを提供する。内部実装は `UICollectionView` ベースで、メインは paging、
+ストリップは自作レイアウトで進行度に応じた stride 補間を行う。
+
+典型的な使い方は ``PhotoScrubberCoupling`` にデータソースを設定し、
+``PhotoScrubberCoupling/scrubView`` と ``PhotoScrubberCoupling/stripView`` を
+任意のレイアウトに配置して ``PhotoScrubberCoupling/reloadData()`` を呼ぶだけ。
+
+```swift
+let coupling = PhotoScrubberCoupling()
+coupling.dataSource = self
+coupling.delegate = self      // optional
+coupling.prefetcher = self    // optional
+coupling.reloadData()
+```
+
+メイン単体でよい場合は ``CustomScrubView`` / ``CustomScrubViewController`` を、
+サムネイル帯だけが必要なら ``ScrubberStripView`` を直接使える。
+
+## Topics
+
+### 連動コンテナ
+
+- ``PhotoScrubberCoupling``
+- ``PhotoScrubberDataSource``
+- ``PhotoScrubberDelegate``
+- ``PhotoScrubberPrefetching``
+- ``PhotoScrubberItemKind``
+
+### メインビュー
+
+- ``CustomScrubView``
+- ``CustomScrubViewController``
+- ``CustomScrubViewDataSource``
+- ``CustomScrubViewDelegate``
+
+### サムネイル帯
+
+- ``ScrubberStripView``
+- ``ScrubberThumbnailDataSource``
+- ``ScrubberStripViewDelegate``
+
+### 共通
+
+- ``ScrubAxis``

Sources/PhotoScrubberKit/PhotoScrubberPrefetching.swift

@@ -1,7 +1,10 @@
 import UIKit
 
+/// prefetch 依頼がメイン・サムネイルどちらの view に対するものかを表す。
 public enum PhotoScrubberItemKind: Sendable {
+    /// メイン (paging) 側の view。
     case main
+    /// サムネイル帯の view。
     case thumbnail
 }
 
@@ -13,6 +16,14 @@ public enum PhotoScrubberItemKind: Sendable {
 /// 通知する。caller 側で expansion や cancel を制御してよい。
 @MainActor
 public protocol PhotoScrubberPrefetching: AnyObject {
+    /// 周辺 item の事前ロードを依頼する。
+    ///
+    /// - Parameters:
+    ///   - coupling: 依頼元のスクラバー。
+    ///   - indices: 事前ロード対象の item index 群（現在 index ± radius、現在 index は除く）。
+    ///   - kind: 依頼対象がメインかサムネイルか。半径は
+    ///     ``PhotoScrubberCoupling/mainPrefetchRadius`` /
+    ///     ``PhotoScrubberCoupling/thumbnailPrefetchRadius`` で調整する。
     func photoScrubber(_ coupling: PhotoScrubberCoupling,
                        prefetchItemsFor indices: [Int],
                        kind: PhotoScrubberItemKind)