Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: improve lib.compareLists documentation #368360

Merged
merged 1 commit into from
Jan 13, 2025

Conversation

hsjobeki
Copy link
Contributor

Improve the documentation of lib.compareLists

I was motivated by seeing the current documentation of the noogle.dev function of the day 😄
This made me thinking: "we already have a language operator for list comparison ... so whats the difference here"

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:
  • 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/)
  • 25.05 Release Notes (or backporting 24.11 and 25.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.

@hsjobeki

This comment was marked as outdated.

lib/lists.nix Outdated
Compare two lists element-by-element.
Compare two lists element-by-element with a comparison function `cmp`.

List elements are compared in order, the first non-equal pair of elements determines the result.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's be explicit

Suggested change
List elements are compared in order, the first non-equal pair of elements determines the result.
List elements are compared in order, the first non-equal pair of elements determines the result, which is expressed as an integer:
- `-1` if the first element of the first unequal pair is less
- `1` if the first element of the first unequal pair is greater
- `0` if all elements are equal

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is already described in the comparison function argument. I would try to not duplicate this information.

Copy link
Contributor

@fricklerhandwerk fricklerhandwerk Jan 9, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The output of the function should be at the top, I found it hard to grasp what the thing is doing before reading the details. And the final outcome not strictly implied by the signature of the comparison function. We can also describe the output indirectly, e.g.

The result is the integer returned by the comparison function for the first unequal pair in the list, or `0`.

lib/lists.nix Outdated Show resolved Hide resolved
@wegank wegank added the 12.approvals: 1 This PR was reviewed and approved by one reputable person label Jan 2, 2025
@hsjobeki hsjobeki force-pushed the lib/compareLists-2 branch from ea5e99f to 477b98b Compare January 9, 2025 10:25
@wegank wegank removed the 12.approvals: 1 This PR was reviewed and approved by one reputable person label Jan 9, 2025
@infinisil infinisil merged commit 7277b3a into NixOS:master Jan 13, 2025
27 of 30 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants