From 7a3684c60b1a18139033387cb17b8b3e637f891e Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Fri, 5 Apr 2024 10:17:25 +0200
Subject: [PATCH] backend-plugin-api: add doc for service factory
 initialization option

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
---
 packages/backend-plugin-api/api-report.md     |  2 --
 .../src/services/system/types.ts              | 20 +++++++++++++++++++
 2 files changed, 20 insertions(+), 2 deletions(-)

diff --git a/packages/backend-plugin-api/api-report.md b/packages/backend-plugin-api/api-report.md
index 6f6f630850..364459352f 100644
--- a/packages/backend-plugin-api/api-report.md
+++ b/packages/backend-plugin-api/api-report.md
@@ -438,7 +438,6 @@ export interface PluginServiceFactoryConfig<
     deps: ServiceRefsToInstances<TDeps>,
     context: TContext,
   ): TImpl | Promise<TImpl>;
-  // (undocumented)
   initialization?: 'always' | 'lazy';
   // (undocumented)
   service: ServiceRef<TService, 'plugin'>;
@@ -519,7 +518,6 @@ export interface RootServiceFactoryConfig<
   deps: TDeps;
   // (undocumented)
   factory(deps: ServiceRefsToInstances<TDeps, 'root'>): TImpl | Promise<TImpl>;
-  // (undocumented)
   initialization?: 'always' | 'lazy';
   // (undocumented)
   service: ServiceRef<TService, 'root'>;
diff --git a/packages/backend-plugin-api/src/services/system/types.ts b/packages/backend-plugin-api/src/services/system/types.ts
index 9e751cbd39..4f9e0244aa 100644
--- a/packages/backend-plugin-api/src/services/system/types.ts
+++ b/packages/backend-plugin-api/src/services/system/types.ts
@@ -141,6 +141,16 @@ export interface RootServiceFactoryConfig<
   TImpl extends TService,
   TDeps extends { [name in string]: ServiceRef<unknown> },
 > {
+  /**
+   * The initialization strategy for the service factory. This service is root scoped and will use `always` by default.
+   *
+   * @remarks
+   *
+   * - `always` - The service will always be initialized regardless if it is used or not.
+   * - `lazy` - The service will only be initialized if it is depended on by a different service or feature.
+   *
+   * Service factories for root scoped services use `always` as the default, while plugin scoped services use `lazy`.
+   */
   initialization?: 'always' | 'lazy';
   service: ServiceRef<TService, 'root'>;
   deps: TDeps;
@@ -154,6 +164,16 @@ export interface PluginServiceFactoryConfig<
   TImpl extends TService,
   TDeps extends { [name in string]: ServiceRef<unknown> },
 > {
+  /**
+   * The initialization strategy for the service factory. This service is plugin scoped and will use `lazy` by default.
+   *
+   * @remarks
+   *
+   * - `always` - The service will always be initialized regardless if it is used or not.
+   * - `lazy` - The service will only be initialized if it is depended on by a different service or feature.
+   *
+   * Service factories for root scoped services use `always` as the default, while plugin scoped services use `lazy`.
+   */
   initialization?: 'always' | 'lazy';
   service: ServiceRef<TService, 'plugin'>;
   deps: TDeps;