From 1d99ea678b6a45c934bd75d4a03c197f9d44314b Mon Sep 17 00:00:00 2001 From: opficdev <162981733+opficdev@users.noreply.github.com> Date: Mon, 7 Sep 2026 00:33:35 +0900 Subject: [PATCH 1/3] =?UTF-8?q?docs:=20Cradle=20=EA=B3=B5=EA=B0=9C=20API?= =?UTF-8?q?=20Quick=20Help=EC=99=80=20=EC=83=81=EC=84=B8=20DocC=20?= =?UTF-8?q?=EC=97=B0=EA=B2=B0=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Sources/Cradle/DependencyGraph.swift | 21 ++++++++++++++++++++ Sources/Cradle/DependencyGraphLifetime.swift | 9 +++++++++ Sources/Cradle/DependencyLifetime.swift | 12 +++++++++++ Sources/Cradle/DependencyOverride.swift | 9 +++++++++ Sources/Cradle/External.swift | 9 +++++++++ 5 files changed, 60 insertions(+) diff --git a/Sources/Cradle/DependencyGraph.swift b/Sources/Cradle/DependencyGraph.swift index 8e66b1b..4374ead 100644 --- a/Sources/Cradle/DependencyGraph.swift +++ b/Sources/Cradle/DependencyGraph.swift @@ -13,6 +13,17 @@ // final class `sources` source graph 저장 프로퍼티와 생성 initializer 추가 // `overrides: true` graph의 인스턴스별 Factory 선택 builder와 생성 경로 추가 // source·override가 없는 graph의 initializer·stored property 미변경 +/// `@Provide` Factory로 의존성을 등록하고 생성 접근자를 만드는 graph Macro입니다. +/// +/// 제네릭 매개변수와 `where` 절이 없는 `final class` 또는 `actor`에 적용합니다. 일반 `@Provide` Factory의 반환 타입을 기준으로 graph에 읽기 전용 생성 프로퍼티를 추가합니다. +/// +/// 자세한 사용 조건과 제약은 에서 설명합니다. +/// +/// - Parameters: +/// - lifetime: graph 인스턴스의 보유 범위입니다. 기본 `.instance`는 호출자가 만든 graph를 사용하고, `.shared`는 프로세스 동안 보유하는 `static let shared` graph를 만듭니다. +/// - sources: `final class` graph가 보관하고 Factory에서 읽을 source graph 타입 배열입니다. +/// - overrides: graph 인스턴스별 Factory 교체를 위한 `override`와 `OverrideBuilder` 생성 여부입니다. +/// - diagram: `CradlePlugin`의 Mermaid 개발 산출물에 해당 graph를 포함할지 정하는 값입니다. @attached(member, names: arbitrary) public macro DependencyGraph( _ lifetime: DependencyGraphLifetime = .instance, @@ -25,6 +36,11 @@ public macro DependencyGraph( ) // `@DependencyGraph` 본체에서 생성 접근자가 호출할 private factory 표시 +/// 기본 `.shared` 수명으로 의존성을 등록하는 Factory Macro입니다. +/// +/// `@DependencyGraph` 본체에 직접 선언한 동기 `private` 인스턴스 메서드에 적용합니다. Factory 결과는 graph를 만들 때 한 번 생성되고 해당 graph가 보관합니다. +/// +/// 수명 정책과 외부 입력 사용법은 에서 설명합니다. @attached(peer, names: arbitrary) @attached(body) public macro Provide() = #externalMacro( @@ -33,6 +49,11 @@ public macro Provide() = #externalMacro( ) // Factory 결과를 graph 수명 정책에 맞게 소유하도록 표시 +/// 지정한 수명 정책으로 의존성을 등록하는 Factory Macro입니다. +/// +/// `@DependencyGraph` 본체에 직접 선언한 동기 `private` 인스턴스 메서드에 적용합니다. 외부 입력이 없는 Factory의 반환 타입이 등록 타입과 생성 접근자의 타입이 됩니다. `@External` 입력이 있는 `.transient` Factory는 호출 시점 생성 메서드를 만듭니다. +/// +/// - Parameter lifetime: Factory 결과의 graph별 보유 정책입니다. `.shared`, `.lazy`, `.transient`의 차이는 에서 설명합니다. @attached(peer, names: arbitrary) @attached(body) public macro Provide(_ lifetime: DependencyLifetime) = #externalMacro( diff --git a/Sources/Cradle/DependencyGraphLifetime.swift b/Sources/Cradle/DependencyGraphLifetime.swift index 96f318f..594f8fe 100644 --- a/Sources/Cradle/DependencyGraphLifetime.swift +++ b/Sources/Cradle/DependencyGraphLifetime.swift @@ -6,9 +6,18 @@ // // graph 인스턴스의 생성·보유 범위 정책 +/// graph 인스턴스의 생성과 보유 범위를 정하는 정책입니다. +/// +/// `DependencyLifetime`가 Factory 결과의 수명을 정하는 것과 달리 graph 자체의 보유 범위를 정합니다. 자세한 사용 조건은 에서 설명합니다. public enum DependencyGraphLifetime: Sendable { // 호출자가 직접 만드는 graph 인스턴스 범위 + /// 호출자가 직접 생성하고 보유하는 graph 인스턴스 범위입니다. + /// + /// graph 수명과 provider 결과 수명의 차이는 에서 설명합니다. case instance // 프로세스 동안 보유하는 정적 graph 범위 + /// 프로세스 동안 보유하는 `static let shared` graph 범위입니다. + /// + /// graph 수명과 동시성 조건은 에서 설명합니다. case shared } diff --git a/Sources/Cradle/DependencyLifetime.swift b/Sources/Cradle/DependencyLifetime.swift index 1795d86..d57df99 100644 --- a/Sources/Cradle/DependencyLifetime.swift +++ b/Sources/Cradle/DependencyLifetime.swift @@ -6,11 +6,23 @@ // // graph가 Factory 결과를 소유하는 수명 정책 +/// Factory 결과를 graph가 평가하고 보유하는 방식을 정하는 정책입니다. +/// +/// `DependencyGraphLifetime`의 graph 인스턴스 보유 범위와 구분됩니다. 각 정책의 사용 조건은 에서 설명합니다. public enum DependencyLifetime: Sendable { // graph 생성 중 한 번 만들고 해당 graph에서 재사용 + /// graph를 생성할 때 Factory 결과를 한 번 만들고 해당 graph가 보관하는 정책입니다. + /// + /// provider 수명과 graph 수명의 차이는 에서 설명합니다. case shared // 생성 프로퍼티를 처음 읽을 때 graph별로 한 번 생성 + /// 생성 프로퍼티를 처음 읽을 때 Factory 결과를 graph별로 한 번 만드는 정책입니다. + /// + /// provider 수명별 평가 시점은 에서 설명합니다. case lazy // 생성 프로퍼티를 읽을 때마다 Factory를 호출 + /// 생성 프로퍼티를 읽거나 외부 입력 생성 메서드를 호출할 때마다 Factory를 평가하는 정책입니다. + /// + /// 외부 입력과 provider 수명 사용 조건은 에서 설명합니다. case transient } diff --git a/Sources/Cradle/DependencyOverride.swift b/Sources/Cradle/DependencyOverride.swift index 58c9801..426a07d 100644 --- a/Sources/Cradle/DependencyOverride.swift +++ b/Sources/Cradle/DependencyOverride.swift @@ -6,10 +6,19 @@ // // graph 생성 전에 기본 Factory 또는 교체 Factory를 선택하는 상태 +/// graph를 만들기 전에 원본 또는 교체 Factory를 선택하는 값입니다. +/// +/// 선택은 `Graph.override(...).build()`로 만드는 graph 인스턴스에만 적용합니다. `Factory`가 `Sendable`이면 이 값도 `Sendable`을 준수합니다. 자세한 교체 조건은 에서 설명합니다. public enum DependencyOverride { // graph 선언에 작성한 기본 Factory 선택 + /// graph 선언에 작성한 원본 Factory를 선택합니다. + /// + /// 교체 Factory의 적용 범위는 에서 설명합니다. case original // graph 인스턴스에만 적용할 타입 지정 교체 Factory 선택 + /// 생성할 graph 인스턴스에 적용할 교체 Factory를 선택합니다. + /// + /// 이 선택은 Factory를 실행하거나 `Graph.shared`를 변경하지 않습니다. 실행 시점과 제약은 에서 설명합니다. case replace(Factory) } diff --git a/Sources/Cradle/External.swift b/Sources/Cradle/External.swift index e143f79..3b695b4 100644 --- a/Sources/Cradle/External.swift +++ b/Sources/Cradle/External.swift @@ -6,12 +6,21 @@ // // graph 생성 메서드 호출자가 전달할 `@Provide(.transient)` 입력 +/// `@Provide(.transient)` Factory에 호출 시점 외부 입력을 표시하는 property wrapper입니다. +/// +/// graph는 이 값을 등록하거나 생성하지 않습니다. 외부 입력 생성 메서드의 사용 조건은 에서 설명합니다. @propertyWrapper public struct External { // 원본 Factory가 사용할 외부 입력 + /// 원본 Factory 매개변수에 전달할 외부 입력 값입니다. + /// + /// 외부 입력의 생성 경로는 에서 설명합니다. public let wrappedValue: Value // 생성 메서드에서 받은 값을 원본 Factory 매개변수로 전달 + /// 원본 Factory 매개변수에 전달할 외부 입력 값을 저장합니다. + /// + /// 외부 입력 생성 메서드의 사용 조건은 에서 설명합니다. public init(wrappedValue: Value) { self.wrappedValue = wrappedValue } From 294c76630a0c5255374872c42e9b38213fd7b7f3 Mon Sep 17 00:00:00 2001 From: opficdev <162981733+opficdev@users.noreply.github.com> Date: Mon, 7 Sep 2026 01:00:55 +0900 Subject: [PATCH 2/3] =?UTF-8?q?docs:=20Cradle=20=EA=B3=B5=EA=B0=9C=20API?= =?UTF-8?q?=20Quick=20Help=20Markup=20=ED=95=84=EB=93=9C=20=EC=A0=81?= =?UTF-8?q?=EC=9A=A9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Sources/Cradle/DependencyGraph.swift | 61 +++++++++++++------- Sources/Cradle/DependencyGraphLifetime.swift | 34 ++++++++--- Sources/Cradle/DependencyLifetime.swift | 44 ++++++++++---- Sources/Cradle/DependencyOverride.swift | 34 ++++++++--- Sources/Cradle/External.swift | 32 +++++++--- 5 files changed, 145 insertions(+), 60 deletions(-) diff --git a/Sources/Cradle/DependencyGraph.swift b/Sources/Cradle/DependencyGraph.swift index 4374ead..21a1680 100644 --- a/Sources/Cradle/DependencyGraph.swift +++ b/Sources/Cradle/DependencyGraph.swift @@ -13,17 +13,25 @@ // final class `sources` source graph 저장 프로퍼티와 생성 initializer 추가 // `overrides: true` graph의 인스턴스별 Factory 선택 builder와 생성 경로 추가 // source·override가 없는 graph의 initializer·stored property 미변경 -/// `@Provide` Factory로 의존성을 등록하고 생성 접근자를 만드는 graph Macro입니다. -/// -/// 제네릭 매개변수와 `where` 절이 없는 `final class` 또는 `actor`에 적용합니다. 일반 `@Provide` Factory의 반환 타입을 기준으로 graph에 읽기 전용 생성 프로퍼티를 추가합니다. -/// -/// 자세한 사용 조건과 제약은 에서 설명합니다. -/// -/// - Parameters: -/// - lifetime: graph 인스턴스의 보유 범위입니다. 기본 `.instance`는 호출자가 만든 graph를 사용하고, `.shared`는 프로세스 동안 보유하는 `static let shared` graph를 만듭니다. -/// - sources: `final class` graph가 보관하고 Factory에서 읽을 source graph 타입 배열입니다. -/// - overrides: graph 인스턴스별 Factory 교체를 위한 `override`와 `OverrideBuilder` 생성 여부입니다. -/// - diagram: `CradlePlugin`의 Mermaid 개발 산출물에 해당 graph를 포함할지 정하는 값입니다. +/** + `@Provide` Factory로 의존성을 등록하고 생성 접근자를 만드는 graph Macro입니다. + + 제네릭 매개변수와 `where` 절이 없는 `final class` 또는 `actor`에 적용합니다. + 일반 `@Provide` Factory의 반환 타입을 기준으로 graph에 읽기 전용 생성 프로퍼티를 추가합니다. + + - Parameters: + - lifetime: graph 인스턴스의 보유 범위입니다. 기본값은 `.instance`이며, `.shared`는 프로세스 동안 + 보유하는 `static let shared` graph를 만듭니다. + - sources: `final class` 조합 graph가 보관하고 Factory에서 읽을 source graph 타입 배열입니다. + 기본값은 빈 배열입니다. + - overrides: graph 인스턴스별 Factory 교체를 위한 `override`와 `OverrideBuilder` 생성 여부입니다. + 기본값은 `false`입니다. + - diagram: `CradlePlugin`의 Mermaid 개발 산출물에 해당 graph를 포함할지 정하는 값입니다. + 기본값은 `true`입니다. + - Important: `actor` graph에는 `sources`를 사용할 수 없습니다. `sources` 또는 `overrides: true`를 + 사용한 graph에는 initializer를 직접 선언할 수 없습니다. + - SeeAlso: + */ @attached(member, names: arbitrary) public macro DependencyGraph( _ lifetime: DependencyGraphLifetime = .instance, @@ -36,11 +44,15 @@ public macro DependencyGraph( ) // `@DependencyGraph` 본체에서 생성 접근자가 호출할 private factory 표시 -/// 기본 `.shared` 수명으로 의존성을 등록하는 Factory Macro입니다. -/// -/// `@DependencyGraph` 본체에 직접 선언한 동기 `private` 인스턴스 메서드에 적용합니다. Factory 결과는 graph를 만들 때 한 번 생성되고 해당 graph가 보관합니다. -/// -/// 수명 정책과 외부 입력 사용법은 에서 설명합니다. +/** + 기본 `.shared` 수명으로 의존성을 등록하는 Factory Macro입니다. + + `@DependencyGraph` 본체에 직접 선언한 동기 `private` 인스턴스 메서드에 적용합니다. + Factory 결과는 graph를 만들 때 한 번 생성되고 해당 graph가 보관합니다. + + - Important: 호출 시점 입력이 필요하면 `@Provide(.transient)`와 `@External`을 함께 사용합니다. + - SeeAlso: + */ @attached(peer, names: arbitrary) @attached(body) public macro Provide() = #externalMacro( @@ -49,11 +61,18 @@ public macro Provide() = #externalMacro( ) // Factory 결과를 graph 수명 정책에 맞게 소유하도록 표시 -/// 지정한 수명 정책으로 의존성을 등록하는 Factory Macro입니다. -/// -/// `@DependencyGraph` 본체에 직접 선언한 동기 `private` 인스턴스 메서드에 적용합니다. 외부 입력이 없는 Factory의 반환 타입이 등록 타입과 생성 접근자의 타입이 됩니다. `@External` 입력이 있는 `.transient` Factory는 호출 시점 생성 메서드를 만듭니다. -/// -/// - Parameter lifetime: Factory 결과의 graph별 보유 정책입니다. `.shared`, `.lazy`, `.transient`의 차이는 에서 설명합니다. +/** + 지정한 수명 정책으로 의존성을 등록하는 Factory Macro입니다. + + `@DependencyGraph` 본체에 직접 선언한 동기 `private` 인스턴스 메서드에 적용합니다. + 외부 입력이 없는 Factory의 반환 타입이 등록 타입과 생성 접근자의 타입이 됩니다. + + - Parameter lifetime: Factory 결과의 graph별 보유 정책입니다. `.shared`는 graph 생성 중 한 번, + `.lazy`는 생성 프로퍼티를 처음 읽을 때 한 번, `.transient`는 접근할 때마다 Factory를 평가합니다. + - Important: `@External` 입력은 명시적인 `.transient` Factory에서만 사용할 수 있으며, 이때 Macro는 + 호출 시점 생성 메서드를 만듭니다. + - SeeAlso: + */ @attached(peer, names: arbitrary) @attached(body) public macro Provide(_ lifetime: DependencyLifetime) = #externalMacro( diff --git a/Sources/Cradle/DependencyGraphLifetime.swift b/Sources/Cradle/DependencyGraphLifetime.swift index 594f8fe..88c03f8 100644 --- a/Sources/Cradle/DependencyGraphLifetime.swift +++ b/Sources/Cradle/DependencyGraphLifetime.swift @@ -6,18 +6,34 @@ // // graph 인스턴스의 생성·보유 범위 정책 -/// graph 인스턴스의 생성과 보유 범위를 정하는 정책입니다. -/// -/// `DependencyLifetime`가 Factory 결과의 수명을 정하는 것과 달리 graph 자체의 보유 범위를 정합니다. 자세한 사용 조건은 에서 설명합니다. +/** + graph 인스턴스의 생성과 보유 범위를 정하는 정책입니다. + + `DependencyLifetime`이 Factory 결과의 수명을 정하는 것과 달리 graph 자체의 보유 범위를 정합니다. + + - Note: provider 결과의 평가 시점과 보유 방식은 `DependencyLifetime`로 따로 지정합니다. + - SeeAlso: + */ public enum DependencyGraphLifetime: Sendable { // 호출자가 직접 만드는 graph 인스턴스 범위 - /// 호출자가 직접 생성하고 보유하는 graph 인스턴스 범위입니다. - /// - /// graph 수명과 provider 결과 수명의 차이는 에서 설명합니다. + /** + 호출자가 직접 생성하고 보유하는 graph 인스턴스 범위입니다. + + graph가 해제되면 graph가 보관하던 provider 결과의 참조도 놓습니다. + + - Note: provider 결과의 보유 방식은 각 `@Provide`의 `DependencyLifetime`를 따릅니다. + - SeeAlso: + */ case instance // 프로세스 동안 보유하는 정적 graph 범위 - /// 프로세스 동안 보유하는 `static let shared` graph 범위입니다. - /// - /// graph 수명과 동시성 조건은 에서 설명합니다. + /** + 프로세스 동안 보유하는 `static let shared` graph 범위입니다. + + `actor`와 `@MainActor` graph는 기존 격리를 유지합니다. 비격리 `final class`는 직접 `Sendable` + 준수를 선언해야 합니다. + + - Warning: 이 graph는 프로세스 동안 보유되므로 해제 시점을 검증하는 대상이 아닙니다. + - SeeAlso: + */ case shared } diff --git a/Sources/Cradle/DependencyLifetime.swift b/Sources/Cradle/DependencyLifetime.swift index d57df99..0558161 100644 --- a/Sources/Cradle/DependencyLifetime.swift +++ b/Sources/Cradle/DependencyLifetime.swift @@ -6,23 +6,43 @@ // // graph가 Factory 결과를 소유하는 수명 정책 -/// Factory 결과를 graph가 평가하고 보유하는 방식을 정하는 정책입니다. -/// -/// `DependencyGraphLifetime`의 graph 인스턴스 보유 범위와 구분됩니다. 각 정책의 사용 조건은 에서 설명합니다. +/** + Factory 결과를 graph가 평가하고 보유하는 방식을 정하는 정책입니다. + + `DependencyGraphLifetime`의 graph 인스턴스 보유 범위와 구분됩니다. + + - Note: 이 정책은 graph 자체의 생성 방식이나 보유 기간을 변경하지 않습니다. + - SeeAlso: + */ public enum DependencyLifetime: Sendable { // graph 생성 중 한 번 만들고 해당 graph에서 재사용 - /// graph를 생성할 때 Factory 결과를 한 번 만들고 해당 graph가 보관하는 정책입니다. - /// - /// provider 수명과 graph 수명의 차이는 에서 설명합니다. + /** + graph를 생성할 때 Factory 결과를 한 번 만들고 해당 graph가 보관하는 정책입니다. + + 같은 graph 인스턴스의 생성 프로퍼티를 여러 번 읽어도 같은 결과를 반환합니다. + + - Note: 전역 singleton이 아니라 graph 인스턴스별로 결과를 보관합니다. + - SeeAlso: + */ case shared // 생성 프로퍼티를 처음 읽을 때 graph별로 한 번 생성 - /// 생성 프로퍼티를 처음 읽을 때 Factory 결과를 graph별로 한 번 만드는 정책입니다. - /// - /// provider 수명별 평가 시점은 에서 설명합니다. + /** + 생성 프로퍼티를 처음 읽을 때 Factory 결과를 graph별로 한 번 만드는 정책입니다. + + Factory는 첫 접근 시점의 graph 상태를 읽고, 생성한 결과는 해당 graph가 보관합니다. + + - Warning: `Sendable`을 준수하는 비격리 class의 `.shared` graph에는 사용할 수 없습니다. + - SeeAlso: + */ case lazy // 생성 프로퍼티를 읽을 때마다 Factory를 호출 - /// 생성 프로퍼티를 읽거나 외부 입력 생성 메서드를 호출할 때마다 Factory를 평가하는 정책입니다. - /// - /// 외부 입력과 provider 수명 사용 조건은 에서 설명합니다. + /** + 생성 프로퍼티를 읽거나 외부 입력 생성 메서드를 호출할 때마다 Factory를 평가하는 정책입니다. + + graph는 생성한 결과를 보관하지 않습니다. + + - Important: 호출 시점 입력이 필요하면 Factory 매개변수에 `@External`을 함께 사용합니다. + - SeeAlso: + */ case transient } diff --git a/Sources/Cradle/DependencyOverride.swift b/Sources/Cradle/DependencyOverride.swift index 426a07d..1aab334 100644 --- a/Sources/Cradle/DependencyOverride.swift +++ b/Sources/Cradle/DependencyOverride.swift @@ -6,19 +6,35 @@ // // graph 생성 전에 기본 Factory 또는 교체 Factory를 선택하는 상태 -/// graph를 만들기 전에 원본 또는 교체 Factory를 선택하는 값입니다. -/// -/// 선택은 `Graph.override(...).build()`로 만드는 graph 인스턴스에만 적용합니다. `Factory`가 `Sendable`이면 이 값도 `Sendable`을 준수합니다. 자세한 교체 조건은 에서 설명합니다. +/** + graph를 만들기 전에 원본 또는 교체 Factory를 선택하는 값입니다. + + 선택은 `Graph.override(...).build()`로 만드는 graph 인스턴스에만 적용합니다. + + - Important: 선택 단계에서는 Factory를 실행하거나 `Graph.shared`를 변경하지 않습니다. + - Note: `Factory`가 `Sendable`이면 이 값도 `Sendable`을 준수합니다. + - SeeAlso: + */ public enum DependencyOverride { // graph 선언에 작성한 기본 Factory 선택 - /// graph 선언에 작성한 원본 Factory를 선택합니다. - /// - /// 교체 Factory의 적용 범위는 에서 설명합니다. + /** + graph 선언에 작성한 원본 Factory를 선택합니다. + + `Graph.override(...)`에서 생략한 등록에도 이 선택을 적용합니다. + + - Note: 원본 Factory의 평가 시점은 해당 등록의 `DependencyLifetime`를 따릅니다. + - SeeAlso: + */ case original // graph 인스턴스에만 적용할 타입 지정 교체 Factory 선택 - /// 생성할 graph 인스턴스에 적용할 교체 Factory를 선택합니다. - /// - /// 이 선택은 Factory를 실행하거나 `Graph.shared`를 변경하지 않습니다. 실행 시점과 제약은 에서 설명합니다. + /** + 생성할 graph 인스턴스에 적용할 타입 지정 교체 Factory를 선택합니다. + + 교체 Factory의 매개변수 타입과 순서, 반환 타입은 원본 `@Provide` Factory와 같습니다. + + - Important: 교체 Factory의 평가 시점과 결과 보유 방식은 원본 등록의 `DependencyLifetime`를 따릅니다. + - SeeAlso: + */ case replace(Factory) } diff --git a/Sources/Cradle/External.swift b/Sources/Cradle/External.swift index 3b695b4..841d1d0 100644 --- a/Sources/Cradle/External.swift +++ b/Sources/Cradle/External.swift @@ -6,21 +6,35 @@ // // graph 생성 메서드 호출자가 전달할 `@Provide(.transient)` 입력 -/// `@Provide(.transient)` Factory에 호출 시점 외부 입력을 표시하는 property wrapper입니다. -/// -/// graph는 이 값을 등록하거나 생성하지 않습니다. 외부 입력 생성 메서드의 사용 조건은 에서 설명합니다. +/** + `@Provide(.transient)` Factory에 호출 시점 외부 입력을 표시하는 property wrapper입니다. + + Macro는 `@External` 매개변수만 호출자가 전달하는 생성 메서드를 만들고, 나머지 매개변수는 graph 등록으로 + 연결합니다. + + - Important: graph는 이 값을 등록하거나 보관하지 않으며, 명시적인 `.transient` Factory에서만 사용할 수 + 있습니다. + - SeeAlso: + */ @propertyWrapper public struct External { // 원본 Factory가 사용할 외부 입력 - /// 원본 Factory 매개변수에 전달할 외부 입력 값입니다. - /// - /// 외부 입력의 생성 경로는 에서 설명합니다. + /** + 원본 Factory 매개변수에 전달할 외부 입력 값입니다. + + - Note: 생성된 호출 시점 메서드의 서명이나 반환 결과에는 `External`가 노출되지 않습니다. + - SeeAlso: + */ public let wrappedValue: Value // 생성 메서드에서 받은 값을 원본 Factory 매개변수로 전달 - /// 원본 Factory 매개변수에 전달할 외부 입력 값을 저장합니다. - /// - /// 외부 입력 생성 메서드의 사용 조건은 에서 설명합니다. + /** + 원본 Factory 매개변수에 전달할 외부 입력 값을 저장합니다. + + - Parameter wrappedValue: 생성된 호출 시점 메서드가 원본 Factory에 전달할 값입니다. + - Note: 이 initializer는 Macro가 생성한 Factory 호출 경로에서 wrapper 값을 구성합니다. + - SeeAlso: + */ public init(wrappedValue: Value) { self.wrappedValue = wrappedValue } From 0d4a4faf98f94ae957660935f10213240fa41826 Mon Sep 17 00:00:00 2001 From: opficdev <162981733+opficdev@users.noreply.github.com> Date: Mon, 7 Sep 2026 01:16:25 +0900 Subject: [PATCH 3/3] =?UTF-8?q?docs:=20=EC=9E=91=EB=8F=99=ED=95=98?= =?UTF-8?q?=EC=A7=80=20=EC=95=8A=EB=8A=94=20SeeAlso=20=EC=A0=9C=EA=B1=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Sources/Cradle/DependencyGraph.swift | 3 --- Sources/Cradle/DependencyGraphLifetime.swift | 3 --- Sources/Cradle/DependencyLifetime.swift | 4 ---- Sources/Cradle/DependencyOverride.swift | 3 --- Sources/Cradle/External.swift | 3 --- 5 files changed, 16 deletions(-) diff --git a/Sources/Cradle/DependencyGraph.swift b/Sources/Cradle/DependencyGraph.swift index 21a1680..e5fb9d1 100644 --- a/Sources/Cradle/DependencyGraph.swift +++ b/Sources/Cradle/DependencyGraph.swift @@ -30,7 +30,6 @@ 기본값은 `true`입니다. - Important: `actor` graph에는 `sources`를 사용할 수 없습니다. `sources` 또는 `overrides: true`를 사용한 graph에는 initializer를 직접 선언할 수 없습니다. - - SeeAlso: */ @attached(member, names: arbitrary) public macro DependencyGraph( @@ -51,7 +50,6 @@ public macro DependencyGraph( Factory 결과는 graph를 만들 때 한 번 생성되고 해당 graph가 보관합니다. - Important: 호출 시점 입력이 필요하면 `@Provide(.transient)`와 `@External`을 함께 사용합니다. - - SeeAlso: */ @attached(peer, names: arbitrary) @attached(body) @@ -71,7 +69,6 @@ public macro Provide() = #externalMacro( `.lazy`는 생성 프로퍼티를 처음 읽을 때 한 번, `.transient`는 접근할 때마다 Factory를 평가합니다. - Important: `@External` 입력은 명시적인 `.transient` Factory에서만 사용할 수 있으며, 이때 Macro는 호출 시점 생성 메서드를 만듭니다. - - SeeAlso: */ @attached(peer, names: arbitrary) @attached(body) diff --git a/Sources/Cradle/DependencyGraphLifetime.swift b/Sources/Cradle/DependencyGraphLifetime.swift index 88c03f8..91ebed9 100644 --- a/Sources/Cradle/DependencyGraphLifetime.swift +++ b/Sources/Cradle/DependencyGraphLifetime.swift @@ -12,7 +12,6 @@ `DependencyLifetime`이 Factory 결과의 수명을 정하는 것과 달리 graph 자체의 보유 범위를 정합니다. - Note: provider 결과의 평가 시점과 보유 방식은 `DependencyLifetime`로 따로 지정합니다. - - SeeAlso: */ public enum DependencyGraphLifetime: Sendable { // 호출자가 직접 만드는 graph 인스턴스 범위 @@ -22,7 +21,6 @@ public enum DependencyGraphLifetime: Sendable { graph가 해제되면 graph가 보관하던 provider 결과의 참조도 놓습니다. - Note: provider 결과의 보유 방식은 각 `@Provide`의 `DependencyLifetime`를 따릅니다. - - SeeAlso: */ case instance // 프로세스 동안 보유하는 정적 graph 범위 @@ -33,7 +31,6 @@ public enum DependencyGraphLifetime: Sendable { 준수를 선언해야 합니다. - Warning: 이 graph는 프로세스 동안 보유되므로 해제 시점을 검증하는 대상이 아닙니다. - - SeeAlso: */ case shared } diff --git a/Sources/Cradle/DependencyLifetime.swift b/Sources/Cradle/DependencyLifetime.swift index 0558161..02a8f1d 100644 --- a/Sources/Cradle/DependencyLifetime.swift +++ b/Sources/Cradle/DependencyLifetime.swift @@ -12,7 +12,6 @@ `DependencyGraphLifetime`의 graph 인스턴스 보유 범위와 구분됩니다. - Note: 이 정책은 graph 자체의 생성 방식이나 보유 기간을 변경하지 않습니다. - - SeeAlso: */ public enum DependencyLifetime: Sendable { // graph 생성 중 한 번 만들고 해당 graph에서 재사용 @@ -22,7 +21,6 @@ public enum DependencyLifetime: Sendable { 같은 graph 인스턴스의 생성 프로퍼티를 여러 번 읽어도 같은 결과를 반환합니다. - Note: 전역 singleton이 아니라 graph 인스턴스별로 결과를 보관합니다. - - SeeAlso: */ case shared // 생성 프로퍼티를 처음 읽을 때 graph별로 한 번 생성 @@ -32,7 +30,6 @@ public enum DependencyLifetime: Sendable { Factory는 첫 접근 시점의 graph 상태를 읽고, 생성한 결과는 해당 graph가 보관합니다. - Warning: `Sendable`을 준수하는 비격리 class의 `.shared` graph에는 사용할 수 없습니다. - - SeeAlso: */ case lazy // 생성 프로퍼티를 읽을 때마다 Factory를 호출 @@ -42,7 +39,6 @@ public enum DependencyLifetime: Sendable { graph는 생성한 결과를 보관하지 않습니다. - Important: 호출 시점 입력이 필요하면 Factory 매개변수에 `@External`을 함께 사용합니다. - - SeeAlso: */ case transient } diff --git a/Sources/Cradle/DependencyOverride.swift b/Sources/Cradle/DependencyOverride.swift index 1aab334..f743d98 100644 --- a/Sources/Cradle/DependencyOverride.swift +++ b/Sources/Cradle/DependencyOverride.swift @@ -13,7 +13,6 @@ - Important: 선택 단계에서는 Factory를 실행하거나 `Graph.shared`를 변경하지 않습니다. - Note: `Factory`가 `Sendable`이면 이 값도 `Sendable`을 준수합니다. - - SeeAlso: */ public enum DependencyOverride { // graph 선언에 작성한 기본 Factory 선택 @@ -23,7 +22,6 @@ public enum DependencyOverride { `Graph.override(...)`에서 생략한 등록에도 이 선택을 적용합니다. - Note: 원본 Factory의 평가 시점은 해당 등록의 `DependencyLifetime`를 따릅니다. - - SeeAlso: */ case original // graph 인스턴스에만 적용할 타입 지정 교체 Factory 선택 @@ -33,7 +31,6 @@ public enum DependencyOverride { 교체 Factory의 매개변수 타입과 순서, 반환 타입은 원본 `@Provide` Factory와 같습니다. - Important: 교체 Factory의 평가 시점과 결과 보유 방식은 원본 등록의 `DependencyLifetime`를 따릅니다. - - SeeAlso: */ case replace(Factory) } diff --git a/Sources/Cradle/External.swift b/Sources/Cradle/External.swift index 841d1d0..ebffa28 100644 --- a/Sources/Cradle/External.swift +++ b/Sources/Cradle/External.swift @@ -14,7 +14,6 @@ - Important: graph는 이 값을 등록하거나 보관하지 않으며, 명시적인 `.transient` Factory에서만 사용할 수 있습니다. - - SeeAlso: */ @propertyWrapper public struct External { @@ -23,7 +22,6 @@ public struct External { 원본 Factory 매개변수에 전달할 외부 입력 값입니다. - Note: 생성된 호출 시점 메서드의 서명이나 반환 결과에는 `External`가 노출되지 않습니다. - - SeeAlso: */ public let wrappedValue: Value @@ -33,7 +31,6 @@ public struct External { - Parameter wrappedValue: 생성된 호출 시점 메서드가 원본 Factory에 전달할 값입니다. - Note: 이 initializer는 Macro가 생성한 Factory 호출 경로에서 wrapper 값을 구성합니다. - - SeeAlso: */ public init(wrappedValue: Value) { self.wrappedValue = wrappedValue