improve docs / comments

docs/changes.rst

@@ -171,11 +171,10 @@ New features:
 - WIP packs project, major repo format changes, you must create new repos! #8572
 - rest:// repository URLs - connect via ssh to remote borgstore REST server,
   talking http via stdio, #9593
-- ``borg serve --rest`` serves a current (non-legacy) repository as the
-  server-side component of a rest:// repository (HTTP over stdio). A rest://
-  client now starts ``borg serve --rest`` on the remote, so a remote only needs
-  ``borg`` installed (no separate ``borgstore-server-rest``). Plain ``borg serve``
-  (no option) remains the legacy borg-1.x server.
+- ``borg serve --rest`` serves a (non-legacy) repository as the remote-side
+  component of a rest:// repository (HTTP over stdio). A rest:// client then
+  starts ``borg serve --rest`` on the remote.
+  ``borg serve`` (without --rest) serves legacy borg 1.x repositories.
 - removed ssh:// and socket:// support for current repositories; use a rest://
   repository instead (it can tunnel over ssh). ssh:// and ``borg serve`` remain
   available only for legacy (borg 1.x / v1) repositories, e.g. for

docs/quickstart.rst

@@ -364,8 +364,7 @@ Borg can initialize and access repositories on remote hosts if the
 host is accessible using SSH.  This is fastest and easiest when Borg
 is installed on the remote host, in which case a ``rest://`` repository URL is
 used. Borg connects via SSH and runs ``borg serve --rest`` on the remote host,
-which serves the repository talking HTTP over stdio (so the remote only needs
-``borg`` installed)::
+which serves the repository talking HTTP over stdio::
 
   $ borg -r rest://user@hostname:port/path/to/repo repo-create ...
 

src/borg/archiver/__init__.py

@@ -339,12 +339,14 @@ class Archiver(
                 # everything else comes from the forced "borg serve" command (or the defaults).
                 # stuff from denylist must never be used from the client.
                 denylist = {"restrict_to_paths", "restrict_to_repositories", "umask", "permissions"}
-                # "backend" is the rest:// repository the client wants to access (borg serve --rest
-                # --backend FILE:<path>). Like the legacy repo path (transmitted via the RPC protocol),
-                # the client chooses *which* repo; the forced command pins the restrictions, and
-                # do_serve_rest validates the client backend against restrict_to_paths/repositories.
+                # "backend" is given by the client to the REST server to contruct a posixfs backend
+                # that shall be used as a repository (borg serve --rest --backend FILE:<path>).
+                # Like the legacy repository path (transmitted via the RPC protocol),
+                # the client chooses *which* repository it wants to use; the ssh forced command pins the
+                # restrictions, and do_serve_rest validates the client backend against restrict_to_paths
+                # and restrict_to_repositories.
                 # The --rest mode flag itself is intentionally NOT allowlisted, so the forced command
-                # keeps pinning the mode (legacy vs rest).
+                # keeps pinning the mode (legacy/rpc vs. non-legacy/rest).
                 allowlist = {"debug_topics", "lock_wait", "log_level", "backend"}
                 not_present = object()
                 for attr_name in allowlist: