add kdoc for close, mark more API as @SettingsInternalApi

GitOrigin-RevId: 72485b284105e7d74d7a9a5377827bde198a731c

platform/settings-local/src/com/intellij/platform/settings/local/SettingsControllerMediator.kt

@@ -14,8 +14,7 @@ import org.jetbrains.annotations.VisibleForTesting
 import java.nio.file.Path
 
 @VisibleForTesting
-internal val SETTINGS_CONTROLLER_EP_NAME: ExtensionPointName<DelegatedSettingsController> =
-  ExtensionPointName("com.intellij.settingsController")
+internal val SETTINGS_CONTROLLER_EP_NAME: ExtensionPointName<DelegatedSettingsController> = ExtensionPointName("com.intellij.settingsController")
 
 @VisibleForTesting
 @SettingsInternalApi

platform/settings/docs/topics/bridge-to-old-api.md

@@ -4,6 +4,41 @@ The new Settings Controller API is currently not intended for use by end clients
 All existing implementations of `PersistenceStateComponent` that don't use the deprecated API `JDOMExternalizable` are fully supported, and no changes are required.
 Support here means that each component property serves as a key, not the whole component.
 
+Each field of a state class is represented by a key. The value is stored in a unified format (see below), rather than in XML as found in regular storage files.
+
+```xml
+<component name="TextDiffSettings">
+  <option name="SHARED_SETTINGS">
+    <SharedSettings>
+      <option name="CONTEXT_RANGE" value="8"/>
+      <option name="ENABLE_ALIGNING_CHANGES_MODE" value="false"/>
+      <option name="MERGE_AUTO_APPLY" value="true"/>
+      <option name="MERGE_LIST_GUTTER_MARKERS" value="false"/>
+    </SharedSettings>
+  </option>
+</component>
+```
+
+Only top-level fields serve as keys. In this example, `TextDiffSettings.SHARED_SETTINGS` is the key.
+What if you want to control only `CONTEXT_RANGE`? To avoid a complicated API, nested beans are not supported. 
+That's why a unified format was introduced. This format allows you to work with values in a uniform way using the convenient [kotlinx serialization API](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/-json-element/).
+
+The XML value above in unified format will be a JSON:
+
+```json
+{
+  "shared_settings": {
+    "context_range": 8,
+    "enable_aligning_changes_mode": false,
+    "merge_auto_apply": true,
+    "merge_list_gutter_markers": true
+  }
+}
+```
+
+A unified format provides a robust and straightforward method to decompose values and manage sub-values, if necessary.
+This approach helps avoid dealing with multiple representations of the same data.
+
 ## Unified Format
 
 The Settings Controller operates with values in a unified format, where each value is a [JsonElement](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/-json-element/).

platform/settings/docs/topics/setting-descriptor.md

@@ -2,13 +2,13 @@
 
 `SettingDescriptor` has two required properties:
 
- * key
- * pluginId
+ * key,
+ * pluginId (`PluginId`).
 
-and two optional ones:
+And two optional ones:
 
- * tags (`SettingTag`)
- * serializer (`SettingSerializerDescriptor`)
+ * tags (list of `SettingTag`),
+ * serializer (`SettingSerializerDescriptor`).
 
 The key provided is not the final effective key. The plugin ID is automatically and implicitly prepended to it. 
 The concept of a component name does not exist.
@@ -22,15 +22,15 @@ There is no need for you to use a special group for your plugin settings. The im
 The serializer merely serves as a descriptor for what to serialize, it doesn't implement the serialization itself. 
 The Settings Controller will determine the appropriate serialization format based on the setting tags.
 
-* [Kotlin serialization](https://github.com/Kotlin/kotlinx.serialization/blob/master/docs/serialization-guide.md) is utilized. 
-  The setting values class must be annotated with `kotlinx.serialization.Serializable`. 
+* [Kotlin serialization](https://github.com/Kotlin/kotlinx.serialization/blob/master/docs/serialization-guide.md) is used. 
+  The setting value class must be annotated with `kotlinx.serialization.Serializable`. 
 * You should always specify default values.
 
 ## Tags
 
 The implementation of a settings controller can significantly vary. Therefore, tags should be considered more as hints rather than fixed instructions.
 
-> Why term "tag" and not "attribute" is used?
+> Why is the term "tag" and not "attribute" used?
 > * An attribute often has a value, but a tag does not.
 > * A tag is typically used to categorize or label items.
 > * We don't use a tag with an enum field like `RoamingType`, but rather a simple tag, which is more concise.

platform/settings/src/com/intellij/platform/settings/SettingsController.kt

@@ -29,21 +29,25 @@ interface SettingsController {
   fun createChild(container: ComponentManager): SettingsController?
 
   @Internal
+  @SettingsInternalApi
   fun release()
 
   @Internal
+  @SettingsInternalApi
   fun <T : Any> doGetItem(key: SettingDescriptor<T>): GetResult<T?>
 
   @Internal
+  @SettingsInternalApi
   fun <T : Any> doSetItem(key: SettingDescriptor<T>, value: T?): SetResult
 
   @Internal
+  @SettingsInternalApi
   fun isPersistenceStateComponentProxy(): Boolean
 }
 
 @Internal
 @JvmInline
-value class GetResult<out T : Any?> @PublishedApi internal constructor(@PublishedApi internal val value: Any?) {
+value class GetResult<out T : Any?> @PublishedApi internal constructor(internal val value: Any?) {
   companion object {
     fun <T : Any> resolved(value: T?): GetResult<T?> = GetResult(value)
 
@@ -105,6 +109,9 @@ interface DelegatedSettingsController {
 
   fun createChild(container: ComponentManager): DelegatedSettingsController? = null
 
+  /**
+   * Called when the configuration store is closed, which occurs prior to a full disposal of the service container.
+   */
   fun close() {
   }
 }