diff --git a/lib/services/lib.nix b/lib/services/lib.nix
index 88db80f91494..02587b6bc810 100644
--- a/lib/services/lib.nix
+++ b/lib/services/lib.nix
@@ -37,17 +37,63 @@ rec {
   );
 
   /**
-    This is the entrypoint for the portable part of modular services.
+    Entrypoint for integrating modular services into a containing module system.
 
-    It provides the various options that are consumed by service manager implementations.
+    Each containing system (NixOS, ...) calls `configure` to
+    obtain a `serviceSubmodule` type for its services option. The returned submodule
+    includes the portable service base and any service-manager-specific modules
+    passed via `extraRootModules`.
+
+    **Implementing for a new system** (e.g. home-manager, nix-darwin):
+
+    ```nix
+    # darwin/modules/services/system.nix
+    { lib, config, pkgs, ... }:
+    let
+      portable-lib = import <nixpkgs/lib/services/lib.nix> { inherit lib; };
+
+      modularServiceConfiguration = portable-lib.configure {
+        serviceManagerPkgs = pkgs;
+        extraRootModules = [
+          ./launchd-service.nix    # launchd-specific options (plist generation, etc.)
+        ];
+      };
+    in
+    {
+      options.services = lib.mkOption {
+        type = lib.types.attrsOf modularServiceConfiguration.serviceSubmodule;
+        default = { };
+      };
+
+      config = {
+        # Convert service tree -> launchd plists, assertions, etc.
+        # (analogous to how NixOS converts to systemd units)
+        launchd.agents = ...;
+        assertions = ...;
+        warnings = ...;
+      };
+    }
+    ```
+
+    lib.services.configure :: AttrSet -> { serviceSubmodule :: SubmoduleType }
 
     # Inputs
 
-    `serviceManagerPkgs`: A Nixpkgs instance which will be used for built-in logic such as converting `configData.<path>.text` to a store path.
+    `serviceManagerPkgs`
 
-    `extraRootModules`: Modules to be loaded into the "root" service submodule, but not into its sub-`services`. That's the modules' own responsibility.
+    : 1\. A Nixpkgs instance used for built-in logic such as converting
+    `configData.<path>.text` to a store path.
 
-    `extraRootSpecialArgs`: Fixed module arguments that are provided in a similar manner to `extraRootModules`.
+    `extraRootModules`
+
+    : 2\. Modules to be loaded into the "root" service submodule, but not
+    into its sub-`services`. That's the modules' own responsibility.
+    Typically contains service-manager-specific option modules
+    (e.g. systemd unit options, launchd plist options).
+
+    `extraRootSpecialArgs`
+
+    : 3\. Fixed module arguments provided alongside `extraRootModules`.
 
     # Output