lib: add type signature to some of the functions

[ilkecan]

I was looking for the list difference function using noogle and couldn't find subtractLists initially, because it lacks a type signature.

I tried to add type signatures to most of the non-module or non-internal functions, as best as I could.

Things done

• Built on platform:
  • x86_64-linux
  • aarch64-linux
  • x86_64-darwin
  • aarch64-darwin
• Tested, as applicable:
  • NixOS tests in nixos/tests.
  • Package tests at passthru.tests.
  • Tests in lib/tests or pkgs/test for functions and "core" functionality.
• Ran nixpkgs-review on this PR. See nixpkgs-review usage.
• Tested basic functionality of all binary files, usually in ./result/bin/.
• Nixpkgs Release Notes
  • Package update: when the change is major or breaking.
• NixOS Release Notes
  • Module addition: when adding a new NixOS module.
  • Module update: when the change is significant.
• Fits CONTRIBUTING.md, pkgs/README.md, maintainers/README.md and other READMEs.

[hsjobeki]

Thanks for engineering all the types. I know its a pain. So thanks for doing it :)

I would like to note some minor things for style consistency:
We should probably add some better styleguide if not already described in the doc/contributing

• Section ordering: Examples before Types:
  • Examples are concrete, types are abstract: readers understand a concrete usage example faster than a type signature.
• Type variables:
  • Concrete types start with uppercase: Int, String, Map, Bool, Derivation
  • Type variables start with lowercase: a, b, k, v, m
• If we use Map should we also use List instead of [] ?

EDIT:

Made a PR for the ordering:

#495918

[hsjobeki]

Suggested change

	longestValidPathPrefix :: [String] -> Value -> [String]
	longestValidPathPrefix :: [String] -> Any -> [String]

[hsjobeki]

Can you switch the order of "Examples" vs "Type" ?

[hsjobeki]

Suggested change

	warnOnInstantiate :: string -> Derivation -> Derivation
	warnOnInstantiate :: String -> Derivation -> Derivation

[hsjobeki]

Suggested change

	callPackage :: Path -> {} -> a,
	callPackage :: Path -> AttrSet -> Derivation,

To make it consistent with the rest. Otherwise the {} could be interpreted as the empty set.

[hsjobeki]

Suggested change

	appendToName :: string -> Derivation -> Derivation
	appendToName :: String -> Derivation -> Derivation

Use capital String please. To avoid potential confusion with types.string

I think all named types should be capitalized for consistency.

[hsjobeki]

I am not a big fan of borrowing more from haskell.

In haskell:

1. string should be String: Type names in Haskell must start with an uppercase letter. Lowercase string would be interpreted as a type variable.
2. Parentheses are unnecessary: While not wrong, the parens around Map String Derivation are redundant here.

Idiomatic Haskell:

  lowPrioSet :: Map String Derivation -> Map String Derivation                                                         

If string is intentionally a type variable (i.e., polymorphic over the key type), then it would be valid but you'd
typically use a or k by convention:

  lowPrioSet :: Map k Derivation -> Map k Derivation                                                                   

I would look into some other files in lib first to see if there is convention in place that we can borrow instead.

[hsjobeki]

Suggested change

	and :: bool -> bool -> bool
	and :: Bool -> Bool -> Bool

[hsjobeki]

Suggested change

	compare :: a -> a -> int
	compare :: a -> a -> Int

[hsjobeki]

Suggested change

	toHexString :: int -> string
	toHexString :: Int -> String

[philiptaron]

Holding a PR up with a style rule that wasn't there before is kind of bogus. I think this is fine to merge as-is with the select edits about the types themselves.

[ilkecan]

Section ordering: Examples before Types:

• Examples are concrete, types are abstract: readers understand a concrete usage example faster than a type signature.

Majority of the existing lib functions use the ordering:

• description
• inputs
• outputs
• type
• examples

which is why I have ordered the new type signatures that way and also "fixed" some of the outliers.

Of course current situation should not be an obstacle for possible improvements, but I think this deserves a separate discussion and existing docs should be updated afterwards depending on #495918.

Type variables:

• Concrete types start with uppercase: Int, String, Map, Bool, Derivation
• Type variables start with lowercase: a, b, k, v, m

Yeah, that makes sense to me.

If we use Map should we also use List instead of [] ?

I initially saw { ... } was used for attrs similar to how [ ... ] was used for list on Noogle:

partition :: (a -> bool) -> [a] -> { right :: [a]; wrong :: [a]; }

groupBy :: (a -> String) -> [ a ] -> { [String] :: [a] }

for the builtin functions.

But then saw existing Map usage instead on nixpkgs, which is why I have changed to that myself.

But upon further look, I think nixpkgs also uses { ... } for specific AttrSets and this actually seems more prevalent, so I am going to switch to that.