doc: refactor documentation for lib.{composeExtensions,composeManyExt…

…ensions}

lib/fixed-points.nix

@@ -311,44 +311,79 @@ rec {
  );
 
  /**
- Compose two extending functions of the type expected by 'extends'
- into one where changes made in the first are available in the
- 'super' of the second
+ Compose two overlay functions and return a single overlay function that combines them.
+ For more details see: [composeManyExtensions](#function-library-lib.fixedPoints.composeManyExtensions).
+ */
+ composeExtensions =
+ f: g: final: prev:
+ let fApplied = f final prev;
+ prev' = prev // fApplied;
+ in fApplied // g final prev';
+
+ /**
+ Composes a list of [`overlays`](#chap-overlays) and returns a single overlay function that combines them.
 
+ :::{.note}
+ The result is produced by using the update operator `//`.
+ This means nested values of previous overlays are not merged recursively.
+ In other words, previously defined attributes are replaced, ignoring the previous value, unless referenced by the overlay; for example `final: prev: { foo = final.foo + 1; }`.
+ :::
 
  # Inputs
 
- `f`
+ `extensions`
 
- : 1\. Function argument
+ : A list of overlay functions
+ :::{.note}
+ The order of the overlays in the list is important.
+ :::
 
- `g`
+ : Each overlay function takes two arguments, by convention `final` and `prev`, and returns an attribute set.
+ - `final` is the result of the fixed-point function, with all overlays applied.
+ - `prev` is the result of the previous overlay function.
 
- : 2\. Function argument
 
- `final`
+ # Type
 
- : 3\. Function argument
+ ```
+ # Pseudo code
+ let
+ # final prev
+ # ↓ ↓
+ OverlayFn :: ( { ... } -> { ... } -> { ... } );
+ in
+ composeManyExtensions :: [ OverlayFn ] -> OverlayFn
+ ```
 
- `prev`
+ # Examples
+ :::{.example}
+ ## `lib.fixedPoints.composeManyExtensions` usage example
 
- : 4\. Function argument
- */
- composeExtensions =
- f: g: final: prev:
- let fApplied = f final prev;
- prev' = prev // fApplied;
- in fApplied // g final prev';
+ ```nix
+ let
+ # The "original function" that is extended by the overlays.
+ # Note that it doesn't have prev: as argument since it can be thought of as the first function.
+ original = final: { a = 1; };
 
- /**
- Compose several extending functions of the type expected by 'extends' into
- one where changes made in preceding functions are made available to
- subsequent ones.
+ # Each overlay function has 'final' and 'prev' as arguments.
+ overlayA = final: prev: { b = final.c; c = 3; };
+ overlayB = final: prev: { c = 10; x = prev.c or 5; };
 
+ extensions = composeManyExtensions [ overlayA overlayB ];
+
+ # Caluculate the fixed point of all composed overlays.
+ fixedpoint = lib.fix (lib.extends extensions original );
+
+ in fixedpoint
+ =>
+ {
+ a = 1;
+ b = 10;
+ c = 10;
+ x = 3;
+ }
  ```
- composeManyExtensions : [packageSet -> packageSet -> packageSet] -> packageSet -> packageSet -> packageSet
- ^final ^prev ^overrides ^final ^prev ^overrides
- ```
+ :::
  */
  composeManyExtensions =
  lib.foldr (x: y: composeExtensions x y) (final: prev: {});
@@ -357,17 +392,17 @@ rec {
  Create an overridable, recursive attribute set. For example:
 
  ```
- nix-repl> obj = makeExtensible (self: { })
+ nix-repl> obj = makeExtensible (final: { })
 
  nix-repl> obj
  { __unfix__ = «lambda»; extend = «lambda»; }
 
- nix-repl> obj = obj.extend (self: super: { foo = "foo"; })
+ nix-repl> obj = obj.extend (final: prev: { foo = "foo"; })
 
  nix-repl> obj
  { __unfix__ = «lambda»; extend = «lambda»; foo = "foo"; }
 
- nix-repl> obj = obj.extend (self: super: { foo = super.foo + " + "; bar = "bar"; foobar = self.foo + self.bar; })
+ nix-repl> obj = obj.extend (final: prev: { foo = prev.foo + " + "; bar = "bar"; foobar = final.foo + final.bar; })
 
  nix-repl> obj
  { __unfix__ = «lambda»; bar = "bar"; extend = «lambda»; foo = "foo + "; foobar = "foo + bar"; }