lib/services: improve configure function documentation (#508211)

  );

  /**

    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`

    : 1\. A Nixpkgs instance used for built-in logic such as converting

    `configData.<path>.text` to a store path.

    `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).

    `extraRootModules`: Modules to be loaded into the "root" service submodule, but not into its sub-`services`. That's the modules' own responsibility.

    `extraRootSpecialArgs`

    `extraRootSpecialArgs`: Fixed module arguments that are provided in a similar manner to `extraRootModules`.

    : 3\. Fixed module arguments provided alongside `extraRootModules`.

    # Output