lib.fix: Improve doc #242318

roberth · 2023-07-08T18:16:51Z

The original doc did not help with understanding much, and the wikipedia link was actively harmful.

Description of changes

Starts with succinct reference docs for what is TECHNICALLY a simple function, then goes into explanation.

I wish I could stress "technically" even more. Basically all of its complexity is emergent, as it mirrors a math concept that most programmers are not familiar with, in a language paradigm many aren't familiar with either.

However, it is self-contained and that makes this place a natural location for the explanation.

Things done

The original doc did not help with understanding at all, and the wikipedia link was actively harmful.

tjni

I like the fleshed out explanation building up to how this can work. Thank you.

I left some comments but they are just my opinions and need not be followed up on (or followed up on before merging this PR).

tjni · 2023-07-08T19:40:56Z

lib/fixed-points.nix

-    Compute the fixed point of the given function `f`, which is usually an
-    attribute set that expects its final, non-recursive representation as an
-    argument:
+    `fix f` computes the fixed point of the given function `f`. In other words, the return value is `x` in `x = f x`.


Nit: I think it reads a little better like: "In other words, it returns the value x satisfying x = f x."

tjni · 2023-07-08T19:44:03Z

lib/fixed-points.nix


+    `f` is usually returns an attribute set that expects its final, non-recursive representation as an argument.


Nit: "is usually" => "usually"

tjni · 2023-07-08T19:48:31Z

lib/fixed-points.nix


+    `f` is usually returns an attribute set that expects its final, non-recursive representation as an argument.
+    `f` must be a lazy function.


I personally feel this lazy explanation would be more powerful somewhere in the "How it works" section to give some insight into how it's possible to compute the fixed point.

tjni · 2023-07-08T20:02:36Z

lib/fixed-points.nix


    ```
    nix-repl> fix f
    { bar = "bar"; foo = "foo"; foobar = "foobar"; }
    ```

-    Type: fix :: (a -> a) -> a
+    This example did not _need_ `fix`, and arguably it shouldn't be used in such an example.
+    However, `fix` is useful when your `f` is a parameter, or when it is constructed from higher order functions.


To me, this is an area that can be expanded. To this point, the only example in my mind is the rec attribute set, so f just seems like another way to represent that. It feels like I could pass such an attribute set as a parameter or perhaps construct one from higher order functions without having to pass through fix.

We now refer to extends as a use case.

fricklerhandwerk

Somewhere in there is hidden a great introduction to the module system, but it's not visible yet.

fricklerhandwerk · 2023-07-08T20:12:41Z

lib/fixed-points.nix


    ```
    nix-repl> fix f
    { bar = "bar"; foo = "foo"; foobar = "foobar"; }
    ```

-    Type: fix :: (a -> a) -> a
+    This example did not _need_ `fix`, and arguably it shouldn't be used in such an example.


Why did we choose this example then if it's not helpful to understand practical applications of fix?

fricklerhandwerk · 2023-07-08T20:15:21Z

lib/fixed-points.nix


    ```
    nix-repl> fix f
    { bar = "bar"; foo = "foo"; foobar = "foobar"; }
    ```

-    Type: fix :: (a -> a) -> a
+    This example did not _need_ `fix`, and arguably it shouldn't be used in such an example.
+    However, `fix` is useful when your `f` is a parameter, or when it is constructed from higher order functions.


I can only guess at what this means. Is it when f is a parameter in a scope where we want to evaluate a recursive attrset and therefore we want to abstract over that? (And still why would we do it that way instead of defining a rec set?) What would f constructed from higher order functions look like? Please make an example for each.

fricklerhandwerk · 2023-07-08T20:16:52Z

lib/fixed-points.nix

+    ```nix
+    fix = f:
+      let self = f self; in self;
+    ```


What helped me understand this is an eval trace where we apply x to f and see how self is replaced by x, yielding the let expression in the previous sample.

fricklerhandwerk · 2023-07-08T20:17:53Z

lib/fixed-points.nix

    ```

-    Nix evaluates this recursion until all references to `self` have been
-    resolved. At that point, the final result is returned and `f x = x` holds:
+    `let` bindings are nice, but as it is with `let` bindings in general, we may get more reuse out of the code by defining a function.


This is a very handwavy motivation. It does not explain at all why we would go down that path.

fricklerhandwerk · 2023-07-08T20:30:06Z

lib/fixed-points.nix

-    Compute the fixed point of the given function `f`, which is usually an
-    attribute set that expects its final, non-recursive representation as an
-    argument:
+    `fix f` computes the fixed point of the given function `f`. In other words, the return value is `x` in `x = f x`.


Suggested change

`fix f` computes the fixed point of the given function `f`. In other words, the return value is `x` in `x = f x`.

`fix f` computes the fixed point of the given function `f`.

This is the value that satisfies `f x == x`.

"In other words" is the function definition, we already have that and it doesn't help.

What's missing here though is a non-magical explanation of how that value is found and when it works at all and why.

For instance, you can't say fix (x: 1.0 / x) although clearly the answer should be 1.

You also can't say fix ({a,b,...}: {a=1;b=2;c=a+b;}) for reasons unclear to me.

infinisil · 2023-07-10T16:38:07Z

lib/fixed-points.nix

+    `fix f` computes the fixed point of the given function `f`. In other words, the return value is `x` in `x = f x`.

+    `f` is usually returns an attribute set that expects its final, non-recursive representation as an argument.
+    `f` must be a lazy function.


Suggested change

`fix f` computes the fixed point of the given function `f`. In other words, the return value is `x` in `x = f x`.

`f` is usually returns an attribute set that expects its final, non-recursive representation as an argument.

`f` must be a lazy function.

`fix f` computes `x` such that `x = f x`, also known as the fixed point of `f`.

In other words, it calls `f` with the result of itself.

This can only be meaningful when `x` is a value that can be partially evaluated, such as an attribute set, a list, or a function.

This way, `f` can use one part of `x` to compute another part.

I'd suggest a wording something like this.

An example with a list and a function would also be good.

This is great!

Suggested change

`fix f` computes the fixed point of the given function `f`. In other words, the return value is `x` in `x = f x`.

`f` is usually returns an attribute set that expects its final, non-recursive representation as an argument.

`f` must be a lazy function.

`fix f` computes `x` such that `x == f x`, also known as the fixed point of `f`.

This can only be meaningful when `x` is a value that can be partially evaluated, such as an attribute set, a list, or a function.

This way, `f` can use one part of `x` to compute another part.

I'd remove the "in other words" because it misleads the reader into tying brain knots.

I'd rather you don't edit my own comment fwiw! (why does GitHub even allow that though..) I edited it back now.

In particular, the "This can only be meaningful when" part is intentional, it should not be "This is only meaningful when". Because just using e.g. an attribute set in the result doesn't mean you'll get something "meaningful", e.g. f (attrs: { x = attrs.x + 1; }).

The only thing we know here is that if you don't use an attribute set, a list or a function, it's definitely going to either result in an infinite recursion (f (x: x + 1)), or in a constant value (f (x: 1)), which is definitely not meaningful.

nixos-discourse · 2023-07-14T23:11:11Z

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2023-07-13-documentation-team-meeting-notes-63/30450/1

infinisil · 2023-08-13T19:23:19Z

See also my related proposed rewrite of the extends documentation in #248220

Done together in and after the docs team meeting Co-Authored-By: Robert Hensing <robert@roberthensing.nl>

infinisil

Worked on this together in the docs team meeting today, approved!

Was updated

nixos-discourse · 2023-10-12T15:52:30Z

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2023-10-12-documentation-team-meeting-notes-86/34118/1

lib.fix: Improve doc

1f8b5c0

The original doc did not help with understanding at all, and the wikipedia link was actively harmful.

roberth added the 6.topic: lib The Nixpkgs function library label Jul 8, 2023

roberth requested review from edolstra and infinisil as code owners July 8, 2023 18:16

roberth requested review from fricklerhandwerk and removed request for edolstra and infinisil July 8, 2023 18:17

ofborg bot added 10.rebuild-darwin: 0 10.rebuild-linux: 1-10 labels Jul 8, 2023

tjni approved these changes Jul 8, 2023

View reviewed changes

tjni reviewed Jul 8, 2023

View reviewed changes

fricklerhandwerk previously requested changes Jul 8, 2023

View reviewed changes

infinisil requested changes Jul 10, 2023

View reviewed changes

infinisil mentioned this pull request Aug 9, 2023

Improve the documentation of lib.extends and how it relates to overlays #248220

Merged

1 task

lib.fix: Improve doc more

b82c1c7

Done together in and after the docs team meeting Co-Authored-By: Robert Hensing <robert@roberthensing.nl>

infinisil approved these changes Oct 12, 2023

View reviewed changes

infinisil merged commit b597bff into NixOS:master Oct 12, 2023
19 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

lib.fix: Improve doc #242318

lib.fix: Improve doc #242318

roberth commented Jul 8, 2023

tjni left a comment

tjni Jul 8, 2023

tjni Jul 8, 2023

tjni Jul 8, 2023

tjni Jul 8, 2023

roberth Oct 12, 2023

fricklerhandwerk left a comment

fricklerhandwerk Jul 8, 2023 •

edited

Loading

fricklerhandwerk Jul 8, 2023

fricklerhandwerk Jul 8, 2023

fricklerhandwerk Jul 8, 2023

fricklerhandwerk Jul 8, 2023

infinisil Jul 10, 2023 •

edited

Loading

fricklerhandwerk Jul 10, 2023 •

edited

Loading

infinisil Jul 10, 2023

nixos-discourse commented Jul 14, 2023

infinisil commented Aug 13, 2023

infinisil left a comment

nixos-discourse commented Oct 12, 2023


		`f` is usually returns an attribute set that expects its final, non-recursive representation as an argument.


		`f` is usually returns an attribute set that expects its final, non-recursive representation as an argument.
		`f` must be a lazy function.

	`fix f` computes the fixed point of the given function `f`. In other words, the return value is `x` in `x = f x`.
	`fix f` computes the fixed point of the given function `f`.
	This is the value that satisfies `f x == x`.

-    `fix f` computes the fixed point of the given function `f`. In other words, the return value is `x` in `x = f x`.
-    `f` is usually returns an attribute set that expects its final, non-recursive representation as an argument.
-    `f` must be a lazy function.
+    `fix f` computes `x` such that `x = f x`, also known as the fixed point of `f`.
+    In other words, it calls `f` with the result of itself.
+    This can only be meaningful when `x` is a value that can be partially evaluated, such as an attribute set, a list, or a function.
+    This way, `f` can use one part of `x` to compute another part.

lib.fix: Improve doc #242318

lib.fix: Improve doc #242318

Conversation

roberth commented Jul 8, 2023

Description of changes

Things done

tjni left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

fricklerhandwerk left a comment

Choose a reason for hiding this comment

fricklerhandwerk Jul 8, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

infinisil Jul 10, 2023 • edited Loading

Choose a reason for hiding this comment

fricklerhandwerk Jul 10, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nixos-discourse commented Jul 14, 2023

infinisil commented Aug 13, 2023

infinisil left a comment

Choose a reason for hiding this comment

nixos-discourse commented Oct 12, 2023

fricklerhandwerk Jul 8, 2023 •

edited

Loading

infinisil Jul 10, 2023 •

edited

Loading

fricklerhandwerk Jul 10, 2023 •

edited

Loading