doc: lib.composeExtensions reference to overlays

[hsjobeki]

Description of changes

• Clarify type signature. packageSet is not defined, strictly speaking overlays can be used to extend attribute sets.
• Overlay is a common term that is now linked into its concept chapter.
• Adds concrete function inputs and document them.

Things done

• Built on platform(s)
  • x86_64-linux
  • aarch64-linux
  • x86_64-darwin
  • aarch64-darwin
• For non-Linux: Is sandboxing enabled in nix.conf? (See Nix manual)
  • sandbox = relaxed
  • sandbox = true
• Tested, as applicable:
  • NixOS test(s) (look inside nixos/tests)
  • and/or package tests
  • or, for functions and "core" functionality, tests in lib/tests or pkgs/test
  • made sure NixOS tests are linked to the relevant packages
• Tested compilation of all packages that depend on this change using nix-shell -p nixpkgs-review --run "nixpkgs-review rev HEAD". Note: all changes have to be committed, also see nixpkgs-review usage
• Tested basic functionality of all binary files (usually in ./result/bin/)
• 24.11 Release Notes (or backporting 23.11 and 24.05 Release notes)
  • (Package updates) Added a release notes entry if the change is major or breaking
  • (Module updates) Added a release notes entry if the change is significant
  • (Module addition) Added a release notes entry if adding a new NixOS module
• Fits CONTRIBUTING.md.

---

Add a 👍 reaction to pull requests you find important.

[roberth]

Have a minor suggestions, and a big thing, which is that extends is very relevant for the full picture, so I'm proposing to use it in an example instead.

There's probably a few more improvements that can be made now that we have a complete example, but PR suggestions are not great for doing multiple iterations, so I'll have to give the turn to you ;)

[roberth]

prev' could be gPrev, or it could be inlined, because the name doesn't really add anything, except an unnecessary pointer in the heap.

[roberth]

Btw much respect for opening this.
I aimed to keep my feedback minimal, but the documentation needed significant improvements also prior to your change and I couldn't find a suitable 'incremental' stopping point.
I hope you don't mind, and on the flip side, it will be much better.

[hsjobeki]

Yeah I also realized that understanding overlays is pretty much impossible on their own without also understanding fix ( and later extends).

I just had this idea of a learning path when explaining the concept:
(Initially it is not necessary to understand extends, which makes it easier to understand)

Imagine to use overlays like this. (Which is much simpler to understand before bringing in extends)

fix (flip extensions { /*Initial Prev Set*/ } )

If your initial doesn't depend on final:

Otherwise we could write

fix (final: extensions final { /*Initial Prev Set*/ } )

Which is equivalent to

lib.fix ( lib.extends extensions original );
where
original = final: { /*Initial*/ }

[hsjobeki]

@roberth I've split this now into two PRs. This is the other one. #333389

I feel like we are documenting the same thing twice. So i tried to clean up the api, and only document one of the two functions properly. With a reference on the other one.

[roberth]

I hope I didn't go in a circle too much.
My main input is that by referring to overlays instead of writing out all the parameters we can simplify the documentation and make it easier to understand because we don't have to go into a level of detail that doesn't add any new information that wasn't already in the documentation for the overlay signature.
Adding such redundant information could be useful for explanation-type documentation for studying, but this is reference documentation, so it's not the right place for that kind of elaboration.

[hsjobeki]

All comments should be addressed by now.

[roberth]

A few important suggestions to make it more coherent semantically.
Other than those, LGTM. Nice improvement ❤️

[roberth]

Thanks!