From f48e95d0b7d367672ecb3de80f201e8e72931cdd Mon Sep 17 00:00:00 2001 From: Vladimir Krivosheev Date: Sun, 10 Mar 2024 15:03:29 +0100 Subject: [PATCH] add kdoc for close, mark more API as @SettingsInternalApi GitOrigin-RevId: 72485b284105e7d74d7a9a5377827bde198a731c --- .../local/SettingsControllerMediator.kt | 3 +- .../settings/docs/topics/bridge-to-old-api.md | 35 +++++++++++++++++++ .../docs/topics/setting-descriptor.md | 16 ++++----- .../platform/settings/SettingsController.kt | 9 ++++- 4 files changed, 52 insertions(+), 11 deletions(-) diff --git a/platform/settings-local/src/com/intellij/platform/settings/local/SettingsControllerMediator.kt b/platform/settings-local/src/com/intellij/platform/settings/local/SettingsControllerMediator.kt index 215cd7dc2c31..bc164a96efc1 100644 --- a/platform/settings-local/src/com/intellij/platform/settings/local/SettingsControllerMediator.kt +++ b/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 = - ExtensionPointName("com.intellij.settingsController") +internal val SETTINGS_CONTROLLER_EP_NAME: ExtensionPointName = ExtensionPointName("com.intellij.settingsController") @VisibleForTesting @SettingsInternalApi diff --git a/platform/settings/docs/topics/bridge-to-old-api.md b/platform/settings/docs/topics/bridge-to-old-api.md index 1f3247a1d1ff..095f8d1766a2 100644 --- a/platform/settings/docs/topics/bridge-to-old-api.md +++ b/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 + + + +``` + +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/). diff --git a/platform/settings/docs/topics/setting-descriptor.md b/platform/settings/docs/topics/setting-descriptor.md index e5fed5b13ba6..41c934f98e9e 100644 --- a/platform/settings/docs/topics/setting-descriptor.md +++ b/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. diff --git a/platform/settings/src/com/intellij/platform/settings/SettingsController.kt b/platform/settings/src/com/intellij/platform/settings/SettingsController.kt index 7278a01ed387..d1dbe0086769 100644 --- a/platform/settings/src/com/intellij/platform/settings/SettingsController.kt +++ b/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 doGetItem(key: SettingDescriptor): GetResult @Internal + @SettingsInternalApi fun doSetItem(key: SettingDescriptor, value: T?): SetResult @Internal + @SettingsInternalApi fun isPersistenceStateComponentProxy(): Boolean } @Internal @JvmInline -value class GetResult @PublishedApi internal constructor(@PublishedApi internal val value: Any?) { +value class GetResult @PublishedApi internal constructor(internal val value: Any?) { companion object { fun resolved(value: T?): GetResult = 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() { } }