Document 0.2.3-preview1 Singleton lifecycle changes

docs/getting-started.md

@@ -10,13 +10,13 @@
 The meta package is published as **`Skymly.DesignPatterns`** on [nuget.org](https://www.nuget.org/packages/Skymly.DesignPatterns). C# namespaces remain `DesignPatterns.*`.
 
 ```xml
-<PackageReference Include="Skymly.DesignPatterns" Version="0.2.2" />
+<PackageReference Include="Skymly.DesignPatterns" Version="0.2.3-preview1" />
 ```
 
 Or from the command line:
 
 ```powershell
-dotnet add package Skymly.DesignPatterns --version 0.2.2
+dotnet add package Skymly.DesignPatterns --version 0.2.3-preview1
 ```
 
 ::: warning Early preview
@@ -26,9 +26,9 @@ Public APIs, generated code, and `DP###` diagnostics are **not stable** yet. Pin
 **Optional DI:** the DI integrations are separate packages and are not included in the meta package:
 
 ```powershell
-dotnet add package Skymly.DesignPatterns.Extensions.DependencyInjection --version 0.2.2
+dotnet add package Skymly.DesignPatterns.Extensions.DependencyInjection --version 0.2.3-preview1
 # Or, when using Autofac:
-dotnet add package Skymly.DesignPatterns.Extensions.Autofac --version 0.2.2
+dotnet add package Skymly.DesignPatterns.Extensions.Autofac --version 0.2.3-preview1
 ```
 
 See [Dependency injection](./dependency-injection.md).

docs/index.md

@@ -27,7 +27,7 @@ features:
 ## Status
 
 ::: warning Early preview
-Public APIs, generated code shapes, and diagnostic IDs are **not stable** yet. Install [`Skymly.DesignPatterns`](https://www.nuget.org/packages/Skymly.DesignPatterns) `0.2.2` from nuget.org, or use a sibling clone / pin a commit until a stability announcement.
+Public APIs, generated code shapes, and diagnostic IDs are **not stable** yet. Install [`Skymly.DesignPatterns`](https://www.nuget.org/packages/Skymly.DesignPatterns) `0.2.3-preview1` from nuget.org, or use a sibling clone / pin a commit until a stability announcement.
 :::
 
 ## Where to read next

docs/reference.md

@@ -12,12 +12,12 @@
 
 | Package ID | Version | Contents |
 |------------|-------------------|----------|
-| [`Skymly.DesignPatterns`](https://www.nuget.org/packages/Skymly.DesignPatterns) | `0.2.2` | Meta package — runtime + source generator + analyzers + code fixes |
-| [`Skymly.DesignPatterns.Extensions.DependencyInjection`](https://www.nuget.org/packages/Skymly.DesignPatterns.Extensions.DependencyInjection) | `0.2.2` | MSDI extensions + `RegisterDi` generation |
-| [`Skymly.DesignPatterns.Extensions.Autofac`](https://www.nuget.org/packages/Skymly.DesignPatterns.Extensions.Autofac) | `0.2.2` | Autofac extensions + `RegisterAutofac` generation |
+| [`Skymly.DesignPatterns`](https://www.nuget.org/packages/Skymly.DesignPatterns) | `0.2.3-preview1` | Meta package — runtime + source generator + analyzers + code fixes |
+| [`Skymly.DesignPatterns.Extensions.DependencyInjection`](https://www.nuget.org/packages/Skymly.DesignPatterns.Extensions.DependencyInjection) | `0.2.3-preview1` | MSDI extensions + `RegisterDi` generation |
+| [`Skymly.DesignPatterns.Extensions.Autofac`](https://www.nuget.org/packages/Skymly.DesignPatterns.Extensions.Autofac) | `0.2.3-preview1` | Autofac extensions + `RegisterAutofac` generation |
 
 ```xml
-<PackageReference Include="Skymly.DesignPatterns" Version="0.2.2" />
+<PackageReference Include="Skymly.DesignPatterns" Version="0.2.3-preview1" />
 ```
 
 ::: info Deprecated GitHub-only IDs

docs/samples.md

@@ -40,7 +40,7 @@ The main [DesignPatterns](https://github.com/Skymly/DesignPatterns) CI checks ou
 
 ## NuGet consumption
 
-Package **`Skymly.DesignPatterns` `0.2.2`** is on [nuget.org](https://www.nuget.org/packages/Skymly.DesignPatterns) (early preview). In the samples repo, switch off the sibling project reference:
+Package **`Skymly.DesignPatterns` `0.2.3-preview1`** is on [nuget.org](https://www.nuget.org/packages/Skymly.DesignPatterns) (early preview). In the samples repo, switch off the sibling project reference:
 
 ```powershell
 dotnet run --project DesignPatterns.Samples.Strategy -c Release -p:UseLocalDesignPatterns=false

docs/singleton.md

@@ -16,10 +16,39 @@ public sealed partial class AppSettings
 // Generated: AppSettings.Instance
 ```
 
+## Async initialization
+
+Set `InitializeAsync` to the name of a static initializer returning `Task` or
+`ValueTask`. The generator validates the signature and emits
+`GetInstanceAsync()` instead of the synchronous `Instance` property.
+
+```csharp
+[GenerateSingleton(InitializeAsync = nameof(InitializeAsync))]
+public sealed partial class AppSettings
+{
+    public bool IsInitialized { get; private set; }
+
+    public static ValueTask InitializeAsync(
+        AppSettings instance,
+        CancellationToken cancellationToken)
+    {
+        instance.IsInitialized = true;
+        return ValueTask.CompletedTask;
+    }
+}
+
+var settings = await AppSettings.GetInstanceAsync();
+```
+
 ## Diagnostics
 
 - **DP001** — type must be `partial`
 - **DP002** — invalid target shape
+- **DP067** — async initializer has an invalid signature
+- **DP068** — generated Singleton is also registered as a DI Singleton
+- **DP069** — non-thread-safe generated Singleton contains mutable instance state
+- **DP070** — mutable static Singleton candidate
+- **DP071** — mutable static Singleton is also registered as a DI Singleton
 
 ## Sample
 

docs/zh/getting-started.md

@@ -10,13 +10,13 @@
 元包在 [nuget.org](https://www.nuget.org/packages/Skymly.DesignPatterns) 上的 ID 为 **`Skymly.DesignPatterns`**。C# 命名空间仍为 `DesignPatterns.*`。
 
 ```xml
-<PackageReference Include="Skymly.DesignPatterns" Version="0.2.2" />
+<PackageReference Include="Skymly.DesignPatterns" Version="0.2.3-preview1" />
 ```
 
 也可以使用命令行安装：
 
 ```powershell
-dotnet add package Skymly.DesignPatterns --version 0.2.2
+dotnet add package Skymly.DesignPatterns --version 0.2.3-preview1
 ```
 
 ::: warning 早期预览
@@ -26,9 +26,9 @@ dotnet add package Skymly.DesignPatterns --version 0.2.2
 **可选 DI：** DI 集成作为独立包发布，不包含在元包中：
 
 ```powershell
-dotnet add package Skymly.DesignPatterns.Extensions.DependencyInjection --version 0.2.2
+dotnet add package Skymly.DesignPatterns.Extensions.DependencyInjection --version 0.2.3-preview1
 # 或使用 Autofac：
-dotnet add package Skymly.DesignPatterns.Extensions.Autofac --version 0.2.2
+dotnet add package Skymly.DesignPatterns.Extensions.Autofac --version 0.2.3-preview1
 ```
 
 见[依赖注入](./dependency-injection.md)。

docs/zh/index.md

@@ -27,7 +27,7 @@ features:
 ## 项目状态
 
 ::: warning 早期预览
-公共 API、生成代码形态与诊断 ID **尚未稳定**。请从 nuget.org 安装 [`Skymly.DesignPatterns`](https://www.nuget.org/packages/Skymly.DesignPatterns) `0.2.2`，或使用 sibling 克隆 / 固定 commit，直至稳定公告。
+公共 API、生成代码形态与诊断 ID **尚未稳定**。请从 nuget.org 安装 [`Skymly.DesignPatterns`](https://www.nuget.org/packages/Skymly.DesignPatterns) `0.2.3-preview1`，或使用 sibling 克隆 / 固定 commit，直至稳定公告。
 :::
 
 ## 下一步

docs/zh/reference.md

@@ -12,12 +12,12 @@
 
 | 包 ID | 版本 | 内容 |
 |-------|----------|------|
-| [`Skymly.DesignPatterns`](https://www.nuget.org/packages/Skymly.DesignPatterns) | `0.2.2` | 元包 — 运行时 + 源生成器 + Analyzer + CodeFix |
-| [`Skymly.DesignPatterns.Extensions.DependencyInjection`](https://www.nuget.org/packages/Skymly.DesignPatterns.Extensions.DependencyInjection) | `0.2.2` | MSDI + `RegisterDi` 生成 |
-| [`Skymly.DesignPatterns.Extensions.Autofac`](https://www.nuget.org/packages/Skymly.DesignPatterns.Extensions.Autofac) | `0.2.2` | Autofac + `RegisterAutofac` 生成 |
+| [`Skymly.DesignPatterns`](https://www.nuget.org/packages/Skymly.DesignPatterns) | `0.2.3-preview1` | 元包 — 运行时 + 源生成器 + Analyzer + CodeFix |
+| [`Skymly.DesignPatterns.Extensions.DependencyInjection`](https://www.nuget.org/packages/Skymly.DesignPatterns.Extensions.DependencyInjection) | `0.2.3-preview1` | MSDI + `RegisterDi` 生成 |
+| [`Skymly.DesignPatterns.Extensions.Autofac`](https://www.nuget.org/packages/Skymly.DesignPatterns.Extensions.Autofac) | `0.2.3-preview1` | Autofac + `RegisterAutofac` 生成 |
 
 ```xml
-<PackageReference Include="Skymly.DesignPatterns" Version="0.2.2" />
+<PackageReference Include="Skymly.DesignPatterns" Version="0.2.3-preview1" />
 ```
 
 ::: info 已弃用的 GitHub 包 ID

docs/zh/samples.md

@@ -40,7 +40,7 @@ dotnet run --project DesignPatterns.Samples.Strategy -c Release
 
 ## NuGet 消费
 
-**`Skymly.DesignPatterns` `0.2.2`** 已发布至 [nuget.org](https://www.nuget.org/packages/Skymly.DesignPatterns)（早期预览）。在示例仓关闭 sibling 项目引用：
+**`Skymly.DesignPatterns` `0.2.3-preview1`** 已发布至 [nuget.org](https://www.nuget.org/packages/Skymly.DesignPatterns)（早期预览）。在示例仓关闭 sibling 项目引用：
 
 ```powershell
 dotnet run --project DesignPatterns.Samples.Strategy -c Release -p:UseLocalDesignPatterns=false

docs/zh/singleton.md

@@ -14,10 +14,42 @@ public sealed partial class AppSettings
 }
 ```
 
+## 异步初始化
+
+将 `InitializeAsync` 设置为静态初始化方法的名称。该方法必须返回
+`Task` 或 `ValueTask`，并接收生成的实例与 `CancellationToken`。生成器会校验
+签名，并生成 `GetInstanceAsync()`，不再生成同步的 `Instance` 属性。
+
+```csharp
+[GenerateSingleton(InitializeAsync = nameof(InitializeAsync))]
+public sealed partial class AppSettings
+{
+    public bool IsInitialized { get; private set; }
+
+    public static ValueTask InitializeAsync(
+        AppSettings instance,
+        CancellationToken cancellationToken)
+    {
+        instance.IsInitialized = true;
+        return ValueTask.CompletedTask;
+    }
+}
+
+var settings = await AppSettings.GetInstanceAsync();
+```
+
 ## 诊断
 
 DP001、DP002 — 见 [诊断](./diagnostics.md)。
 
+Singleton 生命周期相关诊断：
+
+- **DP067** — 异步初始化器签名无效
+- **DP068** — 生成的 Singleton 同时注册为 DI Singleton
+- **DP069** — 非线程安全的生成 Singleton 含可变实例状态
+- **DP070** — 可变静态 Singleton 候选
+- **DP071** — 可变静态 Singleton 同时注册为 DI Singleton
+
 ## 示例
 
 [DesignPatterns.Samples.GenerateSingleton](https://github.com/Skymly/DesignPatterns.Samples/tree/main/DesignPatterns.Samples.GenerateSingleton)