Bad or missing documentation on Nix is a known issue. I think a big part of this issue is that the language itself doesn't have a mechanism to provide documentation.

Python has docstrings, Java has javadoc, Hare has haredoc, Lua has emmylua... etc. Every language has SOME WAY of leaving explanation on what a function does, and what values it takes. Nix doesn't seem to have such a thing (if it does, it's a well-kept secret!).

Functions being lazy doesn't help, since that makes it very hard for tools to provide feedback without actually executing the right codepaths. And finding the definition of a function is HARD.