diff --git a/src/core/settings/nm-settings-storage.h b/src/core/settings/nm-settings-storage.h
index 657501528f..8847acc3e6 100644
--- a/src/core/settings/nm-settings-storage.h
+++ b/src/core/settings/nm-settings-storage.h
@@ -27,6 +27,19 @@
 
 struct _NMSettingsPlugin;
 
+/**
+ * NMSettingsStorage:
+ * @_plugin: The settings plugin that provides this storage.
+ * @_uuid: UUID of the profile represented by this storage.
+ * @_filename: Backing filename (can be NULL for in-memory or meta-data).
+ * @_storage_lst: Node in the per-plugin storage list.
+ * @_storage_by_uuid_lst: Node in the per-UUID storage list.
+ *
+ * Describes the origin and identity of one profile instance as provided by a
+ * specific settings plugin and (optionally) a backing file. A single UUID may
+ * have multiple storages from different plugins; plugin order determines
+ * priority.
+ */
 typedef struct NMSettingsStorage {
     GObject                   parent;
     struct _NMSettingsPlugin *_plugin;
diff --git a/src/core/settings/nm-settings.c b/src/core/settings/nm-settings.c
index 959cc2d09b..702c53d5e2 100644
--- a/src/core/settings/nm-settings.c
+++ b/src/core/settings/nm-settings.c
@@ -76,6 +76,17 @@ static NM_CACHED_QUARK_FCN("default-wired-connection-blocked",
 
 /*****************************************************************************/
 
+/**
+ * StorageData:
+ * @sd_lst: Node used in per-UUID storage lists.
+ * @storage: Storage provider instance for this UUID.
+ * @connection: Connection object backed by @storage, or NULL for meta-data.
+ * @prioritize: Request to prioritize this storage during merge.
+ *
+ * Per-UUID storage entry used to accumulate and merge updates from plugins.
+ * Items live temporarily in the dirty list and are merged into the current list
+ * with stable priority ordering.
+ */
 typedef struct _StorageData {
     CList              sd_lst;
     NMSettingsStorage *storage;
@@ -165,6 +176,20 @@ _storage_data_is_alive(StorageData *sd)
 
 /*****************************************************************************/
 
+/**
+ * SettConnEntry:
+ * @uuid: Normalized UUID key for this entry (points to @_uuid_data).
+ * @sett_conn: Current NMSettingsConnection selected for @uuid, or NULL.
+ * @storage: The storage that currently owns @sett_conn, or NULL.
+ * @sd_lst_head: Head of current storages list for @uuid (high to low priority).
+ * @dirty_sd_lst_head: Head of pending storage updates to merge.
+ * @sce_dirty_lst: Node in the global dirty queue.
+ * @_uuid_data: Inline storage backing @uuid.
+ *
+ * Tracks one connection profile across all storages and its dirty state.
+ * It holds the authoritative in-memory connection and the sets of storages
+ * providing or updating it.
+ */
 typedef struct {
     const char           *uuid;
     NMSettingsConnection *sett_conn;