Rewrite comments and docs to drop PR #1749 review-process references

Strip finding IDs (B1, M6, m2, ...), hypothetical-rename stories, and
forward/backward "we used to X, now we Y" narrative from comments and
docs. Replace with descriptions of what the code is and what it does.

Author: Flo0807

demo/test/demo_web/live/preferences_persistence_test.exs

@@ -6,13 +6,9 @@ defmodule DemoWeb.Live.PreferencesPersistenceTest do
   interactions emit a `push_event` with the expected preference key and value
   shape.
 
-  Uses the M6/M7 seams:
-
-    * `Backpex.Preferences.LiveView.event_name/0` — wire event name.
-    * `Backpex.Preferences.Keys.{order,filters,columns}/1` — canonical keys.
-
-  Never string-literal the event name or keys here; the whole point of the
-  seams is that renaming them breaks the emitter and the test in lockstep.
+  The wire event name comes from `Backpex.Preferences.LiveView.event_name/0`
+  and the keys come from `Backpex.Preferences.Keys.{order,filters,columns}/1`,
+  so the test reflects the same contract the emitter uses.
   """
 
   use DemoWeb.ConnCase, async: false
@@ -72,7 +68,7 @@ defmodule DemoWeb.Live.PreferencesPersistenceTest do
 
       # The LiveResource emits several filter-persistence events over the mount
       # + change cycle. We care that at least one of them reflects the new
-      # two-value set and carries the canonical filters key.
+      # two-value set and carries the filters key.
       assert_push_event(view, @event_name, %{
         key: ^expected_key,
         value: %{"published" => ["published", "not_published"]}

guides/live_resource/user-preferences.md

@@ -439,13 +439,14 @@ All three keys route through whichever adapter you configured for
 `"resource.*"` — typically the Session adapter by default, or a per-user DB
 adapter once you wire one up.
 
-### Before / after: migrating a custom macro
+### Replacing a hand-rolled persistence layer
 
-Apps that previously rolled their own persistence (custom `init_order`
-callback backed by a DB table) can delete that scaffolding:
+If your app already persists ordering, filters, or column state through a
+custom `init_order` callback backed by a DB table, the `persist:` option
+replaces that scaffolding:
 
 ```elixir
-# Before
+# Hand-rolled
 use Backpex.LiveResource, adapter_config: [...]
 
 def init_order(assigns), do: MyApp.OrderingSettings.fetch(assigns.current_user, __MODULE__)
@@ -456,7 +457,7 @@ end
 ```
 
 ```elixir
-# After
+# With persist:
 use Backpex.LiveResource,
   adapter_config: [...],
   persist: [:order]

guides/upgrading/v0.19.md

@@ -91,17 +91,16 @@ The `BackpexSidebarSections` hook has been replaced by `BackpexSidebar`, which n
 
 This version introduces a unified preference system that eliminates UI flickering. User preferences (theme, sidebar state, column visibility, etc.) are now server-rendered from a configurable storage backend on every request.
 
-Backpex ships with a Phoenix-session adapter out of the box (matches the legacy behavior — no action needed). Route individual prefixes to a per-user database adapter when you outgrow the ~4KB cookie ceiling or need preferences to follow a user across devices. See the [User Preferences guide](../live_resource/user-preferences.md) for adapter recipes and the opt-in persistence flag for ordering / filters / columns.
+Backpex ships with a Phoenix-session adapter out of the box, so no action is needed to keep preferences in the session. Route individual prefixes to a per-user database adapter when you outgrow the ~4KB cookie ceiling or need preferences to follow a user across devices. See the [User Preferences guide](../live_resource/user-preferences.md) for adapter recipes and the opt-in persistence flag for ordering / filters / columns.
 
 ### Preferences: adapter architecture
 
-- **Terminology.** What was called "cookie-based preferences" is now just
-  "preferences," because storage is pluggable (session, ETS, Ecto, ...). The
-  JS property `BackpexPreferences.cookiePath` was renamed to `endpointPath`
-  — internal to the hook; no change unless you called it directly.
-- **Default behavior is unchanged.** With no config, every key routes to
-  `Backpex.Preferences.Adapters.Session` — identical to the pre-release
-  branch. Existing apps keep working.
+- **Terminology.** Storage is pluggable (session, ETS, Ecto, ...), so the
+  subsystem is called "preferences" rather than "cookie-based preferences."
+  The JS property exposed to hooks is `BackpexPreferences.endpointPath`.
+- **Default behavior.** With no config, every key routes to
+  `Backpex.Preferences.Adapters.Session`, so existing apps need no changes
+  to keep working.
 - **Route a prefix to your database.** Implement
   `Backpex.Preferences.Adapter` and add the route:
 
@@ -116,12 +115,9 @@ Backpex ships with a Phoenix-session adapter out of the box (matches the legacy
 
   Full walkthrough (migration + schema + adapter module, two table shapes)
   in the [User Preferences guide](../live_resource/user-preferences.md).
-- **Per-resource module keys encoding changed.** The internal
-  `resource.<Module>.<suffix>` key now uses `:` as a separator
-  (`resource:<Module>:<suffix>`) so module-name dots don't create
-  accidental path segments. Any values persisted under the previous shape
-  are effectively invalid and will be ignored — no migration is required
-  because the previous shape was only written on this unreleased branch.
+- **Per-resource module keys.** Internal
+  `resource:<Module>:<suffix>` keys use `:` as a separator so module-name
+  dots don't create accidental path segments.
 - **New `persist:` option on `use Backpex.LiveResource`.** Opt in to
   persisting ordering, filters, or column visibility through the
   preferences layer:
@@ -132,9 +128,8 @@ Backpex ships with a Phoenix-session adapter out of the box (matches the legacy
     persist: [:order, :filters, :columns]
   ```
 
-  Not required, not a breaking change — default is `[]`, which preserves
-  Backpex's URL-as-source-of-truth behavior for ordering and filters, and
-  in-memory column visibility.
+  Not required, not a breaking change — default is `[]`, which keeps
+  ordering and filters in the URL and column visibility in-memory.
 
 ### Breaking Changes
 

lib/backpex/preferences.ex

@@ -13,8 +13,7 @@ defmodule Backpex.Preferences do
   ## Zero-config defaults
 
   With no `:backpex, Backpex.Preferences` config set, every key routes to
-  `Backpex.Preferences.Adapters.Session` — matches the legacy single-adapter
-  behavior.
+  `Backpex.Preferences.Adapters.Session`.
 
   ## Configuring per-prefix routing
 
@@ -42,7 +41,7 @@ defmodule Backpex.Preferences do
     * `get_map/3` — read every value under a prefix as a nested map.
     * `put/4` — write from a LiveView socket or `%Plug.Conn{}`.
     * `put_batch/3` — dispatch a list of writes (best-effort, first-error-wins;
-      see the function docs for the partial-success caveat).
+      see the function docs for the partial-success semantics).
   """
 
   alias Backpex.Preferences.Adapters
@@ -57,9 +56,9 @@ defmodule Backpex.Preferences do
   Reads a preference. Falls back to `opts[:default]` when the value is
   missing or the adapter cannot identify the current user.
 
-  Accepts a `%Backpex.Preferences.Context{}` or a bare Phoenix session map —
-  the session-map form is kept for backward compatibility with the legacy
-  `Preferences.get(session, key)` call sites.
+  Accepts a `%Backpex.Preferences.Context{}` or a bare Phoenix session map.
+  The session-map form is convenient for call sites that only have a
+  session on hand.
 
   ## Options
 
@@ -111,10 +110,10 @@ defmodule Backpex.Preferences do
     * `{:ok, value}` — the adapter returned a stored value.
     * `:error` — the adapter successfully determined nothing is stored
       (`{:ok, :not_found}` from the adapter), **or** the adapter returned
-      `{:error, :unidentified}`. Per the
-      `Backpex.Preferences.Adapter` behaviour, `:unidentified` on reads is
-      defined as "treat as not found" — no warning is logged for that case
-      because it is expected (anonymous visitors, background jobs, etc.).
+      `{:error, :unidentified}`. The `Backpex.Preferences.Adapter`
+      behaviour defines `:unidentified` on reads as "treat as not found",
+      so no warning is logged for that case — it is expected (anonymous
+      visitors, background jobs, etc.).
     * `{:error, reason}` — any other adapter failure (e.g. a raised
       exception swallowed by the dispatcher). A warning is also logged.
 
@@ -138,7 +137,7 @@ defmodule Backpex.Preferences do
         {:ok, value}
 
       {_module, {:error, :unidentified}} ->
-        # Per the adapter behaviour, `:unidentified` on reads means "treat as
+        # The adapter behaviour defines `:unidentified` on reads as "treat as
         # not found" — collapse to `:error` without logging. This matches the
         # expected path for anonymous visitors / background jobs that have no
         # resolved identity.
@@ -362,15 +361,17 @@ defmodule Backpex.Preferences do
   def resolve_identity(%Context{} = ctx), do: ctx
 
   @doc """
-  Legacy alias preserved for call sites that still reference the Phoenix
-  session key directly. New code should read
-  `Backpex.Preferences.Adapters.Session.session_key/0`.
+  Returns the Phoenix session key used by the Session adapter.
+
+  Convenience passthrough to `Backpex.Preferences.Adapters.Session.session_key/0`.
   """
   @spec session_key() :: String.t()
   def session_key, do: Adapters.Session.session_key()
 
   @doc """
-  Legacy alias for `Backpex.Preferences.Key.parse/1`.
+  Splits a preference key into path segments.
+
+  Convenience passthrough to `Backpex.Preferences.Key.parse/1`.
   """
   @spec parse_key(String.t()) :: [String.t()]
   def parse_key(key), do: Key.parse(key)

lib/backpex/preferences/adapters/session.ex

@@ -14,9 +14,9 @@ defmodule Backpex.Preferences.Adapters.Session do
   ## Write-path limitations
 
   `put/4` returns `{:error, :requires_http}` for any source other than
-  `:controller`. Writing to a Phoenix session outside an HTTP request cycle is
-  not supported by `Plug.Session`. The dispatcher handles this by falling back
-  to `push_event/3`, which round-trips the write through the browser and the
+  `:controller`. `Plug.Session` cannot write to the Phoenix session outside
+  an HTTP request cycle. The dispatcher handles this by falling back to
+  `push_event/3`, which round-trips the write through the browser and the
   preferences controller.
   """
 

lib/backpex/preferences/context.ex

@@ -12,8 +12,8 @@ defmodule Backpex.Preferences.Context do
   - `from_mount/2` — LiveView mount / on_mount hook (read path).
   - `from_conn/1` — Plug controller (write path over HTTP).
   - `from_socket/2` — server-side preference writes from a LiveView.
-  - `coerce/1` — wraps a bare session map for backward compatibility with the
-    legacy `Backpex.Preferences.get(session, key)` API.
+  - `coerce/1` — wraps a bare session map so callers that only have a
+    session on hand can still use the dispatcher.
 
   ## The `identity` field
 
@@ -45,8 +45,7 @@ defmodule Backpex.Preferences.Context do
   @doc """
   Build a context for a read originating at LiveView mount.
 
-  `assigns` defaults to `%{}` for callers that only have a session (e.g. the
-  legacy `Preferences.get(session, key)` path).
+  `assigns` defaults to `%{}` for callers that only have a session on hand.
   """
   @spec from_mount(map(), map()) :: t()
   def from_mount(session, assigns \\ %{}) when is_map(session) and is_map(assigns) do
@@ -79,8 +78,9 @@ defmodule Backpex.Preferences.Context do
   end
 
   @doc """
-  Wrap a bare session map (or pass through an existing context) so the legacy
-  `Preferences.get(session, key)` call sites keep working.
+  Wrap a bare session map (or pass through an existing context) so call
+  sites that only have a session map can still call `Preferences.get/3` and
+  friends.
 
   Accepts:
 

lib/backpex/preferences/keys.ex

@@ -1,16 +1,11 @@
 defmodule Backpex.Preferences.Keys do
   @moduledoc """
-  Canonical names for all Backpex-managed preference keys.
+  Names for every Backpex-managed preference key.
 
   Every built-in preference (theme, sidebar state, per-resource column
-  visibility, ...) is emitted through a function in this module rather than an
-  inline string literal. This is the single seam for the key namespace: change
-  a value here and every emission plus every test updates in lockstep.
-
-  Renaming `theme/0` from `"global.theme"` to `"global.color_scheme"` would
-  otherwise pass the test suite while silently orphaning every user's stored
-  preference. Routing every literal through this module makes that
-  impossible — the tests break the moment the emitter does.
+  visibility, ...) is produced by a function in this module rather than an
+  inline string literal, so emitters and tests share a single source for
+  the name.
 
   ## Global keys
 
@@ -26,18 +21,18 @@ defmodule Backpex.Preferences.Keys do
   ## Per-resource keys
 
   Per-resource preferences embed the LiveResource module name as a single
-  atomic path segment using the colon-separated key form
-  (`resource:<Module>:<suffix>`). Module names contain dots, so using the
-  colon form keeps the module as one segment rather than splitting into
-  several nested ones.
+  path segment using the colon-separated key form
+  (`resource:<Module>:<suffix>`). Module names contain dots, so the colon
+  form keeps the module as one segment rather than splitting into several
+  nested ones.
 
     * `columns/1` — `"resource:<Module>:columns"`
     * `order/1` — `"resource:<Module>:order"`
     * `filters/1` — `"resource:<Module>:filters"`
     * `metrics_visible/1` — `"resource:<Module>:metrics_visible"`
 
-  Delegates construction to `Backpex.Preferences.Key.resource_key/2` so the
-  encoding stays consistent with other callers of the key helpers.
+  Key construction is delegated to `Backpex.Preferences.Key.resource_key/2`
+  so the encoding stays consistent with other callers of the key helpers.
   """
 
   alias Backpex.Preferences.Key

lib/backpex/preferences/live_view.ex

@@ -2,15 +2,14 @@ defmodule Backpex.Preferences.LiveView do
   @moduledoc """
   LiveView-side helpers for the preferences subsystem.
 
-  The only seam for emitting a preference-write push_event from a LiveView.
-  Centralizes the wire event name so renaming the contract touches exactly
-  one Elixir call site.
-
-  The event name itself is a browser contract — the `BackpexPreferences` JS
-  hook listens for it and POSTs to the preferences controller. Treat it as
-  a stable wire protocol; do not rename without a matching change in
-  `assets/js/hooks/_preferences.js`. The current name is returned from
-  `event_name/0`.
+  Emits preference-write push_events from a LiveView and owns the wire event
+  name that the `BackpexPreferences` JS hook listens for. The hook receives
+  the event, POSTs to the preferences controller, and the controller
+  persists through the configured adapter.
+
+  The event name is a browser contract — treat it as a stable wire protocol
+  and keep it aligned with `assets/js/hooks/_preferences.js`. The name is
+  returned from `event_name/0`.
   """
 
   alias Phoenix.LiveView

lib/backpex/preferences/router.ex

@@ -30,7 +30,7 @@ defmodule Backpex.Preferences.Router do
 
   When no `:adapters` config is set, the router falls back to a single
   `{:default, Backpex.Preferences.Adapters.Session, []}` route so the zero-
-  config behavior matches the legacy single-adapter implementation.
+  config behavior routes every key to the Session adapter.
 
   ## Prefix vs. key resolution
 

test/controllers/preferences_controller_test.exs

@@ -164,8 +164,7 @@ defmodule Backpex.PreferencesControllerTest do
       assert stored["ok.before"] == "committed"
 
       # Short-circuit: the entry after the failure was never dispatched, so
-      # its ETS row was never written. Under the old Enum.reduce/3 it would
-      # have been written and this assertion would fail.
+      # its ETS row was never written.
       refute Map.has_key?(stored, "ok.after")
 
       # Session-backed effects collected before the failure are never applied