how to display the doc-comment in the repl

Seems to work in the repl, Nix 2.25

nix-repl> :doc lib.extend
Function extend
    … defined at /home/user/h/nixpkgs/lib/default.nix:38:20

    Patch the Nixpkgs library
[...]

I guess for nixdoc we'd have to construct a fake sublibrary to represent the top level or something to make it work? We can't just do lib because that has a copy of a majority of functions.

Is there a way to make flake.nix not use a supposed anti-pattern?

lib should have been defined as

lib = {
  lib = import ./lib;
  nixos = ...;
  nixosSystem = ...;
};

Has that ship sailed? Possibly.

Alternatively, we could make nixpkgsFlake.lib.extend "drop" the non-Nixpkgs-library bits by using // instead of extend.
That will still upset some users, but far fewer.

lib = lib // {
  nixos = ...;
  nixosSystem = ...;
};

Maybe add a deprecation warning:

lib = lib.extend (this: old: { nixos = ...; nixosSystem = ...; }) // {
  nixos = ...;
  nixosSystem = ...;
};

Doing the lib.lib thing properly would look like this, and I would guess that over half of all flakes need to be updated for this.
inherit (nixpkgs) lib; -> inherit (nixpkgs.lib) lib;

lib =
  let
    nixpkgsLib = import ./lib;
    warnOnce =
      lib.warnIf
        ( # auto-enables after 24.11 EOL
          lib.oldestSupportedReleaseIsAtLeast 2505)
        # Needs better writing, maybe on nix.dev.
        "The Nixpkgs library is moving into `nixpkgs.lib.lib`. `nixpkgs.lib` is a standard flake output to expose functions and libraries. Nixpkgs exposes its standard library, as well as NixOS functions, such as the `nixos` library and `nixosSystem` function. These remain in `nixpkgs.lib`." null;
  in
    mapAttrs (k: v: builtins.seq warnOnce v) nixpkgsLib // {
      lib = nixpkgsLib;
      nixos = ...;
      nixosSystem = ...;
    }

What do you think?

Before doing any of this, we should have guides for handling dependencies on nix.dev. Things like how do you write a module file that uses bog standard lexical scope stuff instead of fancy tricks like lib.extend or specialArgs.
(hint: importApply or make an anonymous module in flake.nix inject the right option definitions, like { pkgs, ... }: { import = [ ./module.nix ]; services.foo.package = self.packages.${pkgs.stdenv.hostPlatform.system}.foo; })

I think in general the situation currently is quite broken and inconsistent. e.g. a lot of people do not use legacyPackages but import nixpkgs {} to be able to use overlays and they then do not get the extended version of lib anyway.

So I think a breaking change that introduces a lib.lib is worth it. My two cents.

The injecting into the global lib namespace is just ripe with confusion

NixOS/amis@ac17880 is a good example of why I'd love to get rid of all of this. The amount of hoops I need to jump to build a tool for helping release management in nixpkgs due to the oddness of our flake interface is not nice.

NixOS/amis@ac17880 is a good example of why I'd love to get rid of all of this. The amount of hoops I need to jump to build a tool for helping release management in nixpkgs due to the oddness of our flake interface is not nice.

This will then also need changes to lib/flake-version-info.nix. I hope its behavior can be made to match the released channel behavior.