[samhh]

I agree that the documentation story could be better. I also think it's a great shame that the language isn't statically-typed, so to understand how to use something I have to inspect its source code.

I've found it to be quite flexible though. For example, here's a commit in which I apply a patch to a tool to solve a problem that the derivation hadn't taken into account (and absent a home-manager solution): https://github.com/samhh/dotfiles/commit/867dd3b4d4b3942a0aa...

[omaranto]

> I also think it's a great shame that the language isn't statically-typed, so to understand how to use something I have to inspect its source code.

I understand everything in that sentence except the word "so".

[samhh]

Static types are documentative, and language servers often also show you things like JSDoc alongside the type signature. Nix has neither of these, hence I have to check the source code or run a build and see what happens.

I really like Nix but in this particular way it feels like taking a big step backwards from the other languages I frequently use, particularly for a language in which you'll necessarily be constantly interacting with bespoke interfaces.

[omaranto]

Informative function signatures, allowing programmers to add per-function documentation, and tooling that displays those things are by no means limited to staticly typed languages.

I guess knowing allowed types for each parameter is informative (more if very specific types are used rather than string or integer), but documentation usually specifies that anyway. And even knowing all the types isn't usually enough without documentation.

My point is just that I've used plenty of libraries in dynamically typed languages without needing to read the source. And conversely, I've occasionally needed to look at the source of a function in a staticly typed language, to answer some question not answered by the types and documentation.

[SkyMarshal]

Being able to see a function's entire type signature at a glance is the single most useful way of documenting code I've ever come across. No alt-tabbing to docs or relying on an IDE to pop up hints, etc., it's just right there.

Haskell is the ideal here, since it separates the type signature into its own separate line at the top of the function declaration. That confers readability and reduces cognitive overhead more than any other language I've used.

It also changes the programming thought process. You can pseudo-code an entire program just with function type definitions. Then test that the type defs compile without error, and go back and implement the function definitions. As long as the function definitions adhere to their type signature, the program almost always works (barring some I/O errors).

Not all statically typed languages are created equal. The ones fundamentally oriented around function type signatures, rather than variable types, are the ones I think parent had in mind in his comment.