`:doc` doesn't display docs for partially applied primops #1166

New issue

Open

opened 2026-03-21 14:54:56 +00:00 by blokyk · 2 comments

blokyk commented

2026-03-21 14:54:56 +00:00

Describe the bug

When used on a user function, the :doc command will elide already-supplied arguments from the signature. For example, :doc lib.mapAttrsToList's header will display the signature as mapAttrsToList = f: attrs: ..., but :doc lib.mapAttrsToList (n: v: v) will show mapAttrsToList = attrs: ..., dropping the f parameter since it was provided.

However, when used on a primop, such as map, the command :doc map (x: x) will simply error-out, saying that value 'map (x: x)' does not have documentation. This is kind of a shame, it'd be nice if it behaved like normal functions :)

Steps To Reproduce

Open REPL
Load nixpkgs
type :doc map, observe that docs work fine
type :doc map (x: x), get an error :(

Expected behavior

It displays the docs for the function, but removes the already-filled parameters from the signature.

`nix --version` output

nix (Lix, like Nix) 2.94.0
System type: x86_64-linux
Additional system types: i686-linux, x86_64-v1-linux, x86_64-v2-linux, x86_64-v3-linux, x86_64-v4-linux
Features: gc, signed-caches
System configuration file: /etc/nix/nix.conf
User configuration files: /home/blokyk/.config/nix/nix.conf:/etc/xdg/xdg-ubuntu-xorg/nix/nix.conf:/etc/xdg/nix/nix.conf
Store directory: /nix/store
State directory: /nix/var/nix
Data directory: /nix/store/vr4a39d4bw01793jl4qap839rlvmc143-lix-2.94.0/share

Additional context

While messing with the codebase earlier, i noticed that the way the docs are fetched for builtins uses a pretty different mechanism to the rest (namely EvalBuiltins::getDoc), but i didn't have the time to dig deeper, so if someone could pitch in about how feasible this is, i'd really appreciate it :)

## Describe the bug When used on a *user* function, the `:doc` command will elide already-supplied arguments from the signature. For example, `:doc lib.mapAttrsToList`'s header will display the signature as `mapAttrsToList = f: attrs: ...`, but `:doc lib.mapAttrsToList (n: v: v)` will show `mapAttrsToList = attrs: ...`, dropping the `f` parameter since it was provided. However, when used on a *primop*, such as `map`, the command `:doc map (x: x)` will simply error-out, saying that `value 'map (x: x)' does not have documentation`. This is kind of a shame, it'd be nice if it behaved like normal functions :) ## Steps To Reproduce 1. Open REPL 2. Load nixpkgs 3. type `:doc map`, observe that docs work fine 4. type `:doc map (x: x)`, get an error :( ## Expected behavior It displays the docs for the function, but removes the already-filled parameters from the signature. ## `nix --version` output ``` nix (Lix, like Nix) 2.94.0 System type: x86_64-linux Additional system types: i686-linux, x86_64-v1-linux, x86_64-v2-linux, x86_64-v3-linux, x86_64-v4-linux Features: gc, signed-caches System configuration file: /etc/nix/nix.conf User configuration files: /home/blokyk/.config/nix/nix.conf:/etc/xdg/xdg-ubuntu-xorg/nix/nix.conf:/etc/xdg/nix/nix.conf Store directory: /nix/store State directory: /nix/var/nix Data directory: /nix/store/vr4a39d4bw01793jl4qap839rlvmc143-lix-2.94.0/share ``` ## Additional context While messing with the codebase earlier, i noticed that the way the docs are fetched for builtins uses a pretty different mechanism to the rest (namely `EvalBuiltins::getDoc`), but i didn't have the time to dig deeper, so if someone could pitch in about how feasible this is, i'd really appreciate it :)

blokyk added the

bug

label

2026-03-21 14:54:56 +00:00

pennae commented

2026-03-21 15:42:13 +00:00

Owner

cl/5221 wanted to do something similar but got a bit stuck due to larger scope. if you're happy with just solving the map (_:_) case and you don't want to show the docs of the binding this value was bound to (as that cl did) you can retry the getDoc bit for the associated primop

cl/5221 wanted to do something similar but got a bit stuck due to larger scope. if you're happy with *just* solving the `map (_:_)` case and you don't want to show the docs of the binding this value was bound *to* (as that cl did) you can retry the `getDoc` bit for the associated primop

blokyk commented

2026-03-21 15:59:32 +00:00

Author

if i'm not mistaken, even with a normal function, it sometimes ends up showing the underlying value's documentation, instead of the binding for it (which is like the issue that cl tried to fix, but not restricted to primops). i'll admit though that i didn't think about the binding issue enough, i'm not sure that fixing getDoc without doing anything else would work as intended... i'll mess around with it next time i can, but yeah this isn't as trivial as i thought ;-;
(funnily enough i saw that issue and cl a little while ago but completely forgot about it til now)

if i'm not mistaken, even with a normal function, it sometimes ends up showing the underlying value's documentation, instead of the binding for it (which is like [the issue that cl tried to fix](https://git.lix.systems/lix-project/lix/issues/1110), but not restricted to primops). i'll admit though that i didn't think about the binding issue enough, i'm not sure that fixing `getDoc` without doing anything else would work as intended... i'll mess around with it next time i can, but yeah this isn't as trivial as i thought ;-; (funnily enough i saw that issue and cl a little while ago but completely forgot about it til now)