docs: Rewrite Settings and Workspaces documentation (#9065)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: hl662

common/changes/@itwin/core-backend/nam-settings-workspace-docs_2026-04-15-20-20.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "Updated TSDoc for Settings and IModelDb to reference current EditTxn APIs instead of deprecated methods.",
+      "type": "none",
+      "packageName": "@itwin/core-backend"
+    }
+  ],
+  "packageName": "@itwin/core-backend",
+  "email": "50554904+hl662@users.noreply.github.com"
+}

core/backend/src/IModelDb.ts

@@ -2259,6 +2259,7 @@ export abstract class IModelDb extends IModel {
    * @param name The name for the SettingDictionary. If a dictionary by that name already exists in the iModel, its value is replaced.
    * @param dict The SettingDictionary object to stringify and save.
    * @note All saved `SettingDictionary`s are loaded into [[workspace.settings]] every time an iModel is opened.
+   * @see [[Settings.addDictionary]] to register a dictionary for the current session only without persisting it.
    * @beta @deprecated Use EditTxn.saveSettingDictionary instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
    */
   public saveSettingDictionary(name: string, dict: SettingsContainer) {

core/backend/src/workspace/Settings.ts

@@ -203,15 +203,16 @@ export interface SettingsDictionaryProps extends SettingsDictionarySource {
  * Like iModel-specific settings, any settings supplied by the iTwin will override those defined at the application level.
  *
  * Application settings are loaded into [[IModelHost.appWorkspace]] when the session begins (i.e., when [[IModelHost.startup]] is invoked), and unloaded when it ends (in [[IModelHost.shutdown]]).
- * They are read from [JSON5](https://json5.org/) files delivered with the application. The application should register any additional [[SettingsDictionary]]'s '(and their corresponding
- * [[SettingGroupSchema]]s) at this time.
+ * They are read from [JSON5](https://json5.org/) files delivered with the application. The application should register any additional [[SettingsDictionary]]s
+ * (and their corresponding [[SettingGroupSchema]]s) at this time.
  *
  * iModel-specific settings are stored in the iModel's property table and loaded into [[IModelDb.workspace]] when the iModel is first opened.
- * You can add and remove a [[SettingsDictionary]] from the property table using [[IModelDb.saveSettingDictionary]] and [[IModelDb.deleteSettingDictionary]].
+ * You can add and remove a [[SettingsDictionary]] from the property table using [[EditTxn.saveSettingDictionary]] and [[EditTxn.deleteSettingDictionary]].
+ * If you are migrating older code, [[IModelDb.saveSettingDictionary]] and [[IModelDb.deleteSettingDictionary]] are deprecated in favor of the [[EditTxn]] APIs.
  *
  * iTwin-specific settings are stored in a [[CloudSqliteContainer]] in the cloud.
  * When [[IModelHost.getITwinWorkspace]] is invoked, the container is accessed using the iTwinId and the settings are loaded into the returned [[Workspace]].
- * You can add and remove a [[SettingsDictionary]] from the container using [[Workspace.saveSettingsDictionary]] and [[Workspace.deleteSettingsDictionary]].
+ * You can add and remove a [[SettingsDictionary]] from the container using [[IModelHost.saveSettingDictionary]] and [[IModelHost.deleteSettingDictionary]].
  *
  * See the [learning article]($docs/learning/backend/Workspace) for a detailed overview and examples.
  *
@@ -256,6 +257,7 @@ export interface Settings {
 
   /** Add a new [[SettingsDictionary]] with the priority, name, and [[WorkspaceDb]] specified by `props` and setting values supplied by `settings`.
    * @note If a dictionary with the same name and [[WorkspaceDb]] already exists, it will be replaced.
+   * @note Values added via this method exist only for the current session. They are not persisted and will be lost when the host shuts down.
    * @see [[addFile]], [[addJson]], and [[addDirectory]] for convenient ways to add dictionaries from various sources.
    */
   addDictionary(props: SettingsDictionaryProps, settings: SettingsContainer): void;

docs/changehistory/5.8.0.md

@@ -100,7 +100,7 @@ Previously, settings and binary resources (fonts, textures, templates) were stor
 
 ##### Creating a local SettingsDb
 
-See [SettingsDb]($docs/learning/backend/Workspace.md#settingsdb) for full documentation.
+See [Settings containers]($docs/learning/backend/Settings.md#settings-containers) for full documentation.
 
 #### Container type convention
 

docs/changehistory/NextVersion.md

@@ -275,7 +275,7 @@ Delete it:
 
 To use iTwin-scoped settings dictionaries, configure [IModelHost.authorizationClient]($backend) and [BlobContainer.service]($backend) so the backend can query and update the iTwin settings workspace container.
 
-See the [Workspace documentation]($docs/learning/backend/Workspace.md) for full details.
+See the [Settings documentation]($docs/learning/backend/Settings.md#itwin-settings) for full details on iTwin-scoped settings and the [Workspace documentation]($docs/learning/backend/Workspace.md) for workspace resources.
 
 ## Quantity Formatting