Okay, yes, I agree with all of that. Flakes are kind of a module system, but having clearer semantics around functions and classes would definitely help with both code readability and producing better stack traces.

And a proper type system would be awesome.

Regarding docs, it is interesting that portions of the nixpkgs source do seem to have docblock-like comments above the functions, but AFAICT there's no formalized process for extracting or rendering those. Given that https://github.com/nix-community/rnix-parser exists, I wonder how big of a leap it would be to actually extract those, render them into rST pages, and generate a searchable Sphinx manual.