Print docs of expressions returning lambdas in the REPL #1167

New issue

Open

opened 2026-03-21 17:22:24 +00:00 by blokyk · 2 comments

blokyk commented

2026-03-21 17:22:24 +00:00

Sometimes you're in the middle of writing a mildly-long expression using a certain function, when you forget the exact signature or behavior of it (e.g. after writing the first argument), at which point you have two options:

give up and press enter (which just shows you «lambda stuff @ /some/path»), then type :doc lib.annoying.stuff (yes, there's TAB, but still), enter, ↑↑, and finally resume typing your expression
ctrl+← for each token in the expression, then :doc , then ↑↑ restart typing, then enter, then oh fuck i forgot the :doc then restart, then ctrl+← again, then remove, then enter, then sigh

Describe the solution you'd like

If the result of an expression is a non-fully-applied function, print the docs for it (if any) in addition to the «lambda stuff @ /some/path» output it already gave.

Describe alternatives you've considered

Since this is a somewhat opinionated request, one alternative would be to gate this behind some kind of option.

Alternatively, although this is less discoverable and is more of a "long-term dream," improvements in the repl's interface itself, such as keyboard shortcuts or popups, could be helpful in showing docs when the user needs them most but without overloading the repl's output.

The final alternative is to just... not change anything ¯\_(ツ)_/¯

Additional context

With regards to adding this as an option: there is some questions to be answered as to what's the best way to add them.

In addition, i also recognize that the current way the docs work have some problems that could interfere with this scenario. The biggest one I can think of is that the output of :doc for partial functions can be a little confusing if you're not expecting it: although the signature in the header only contains parameters that haven't been supplied yet, the body of the documentation (which is a lot more attention-grabbing than the tiny discrete signature at the top) still has the full list of input, since to nix's eyes it's just formatted text instead of having a clear separate parameter section with an individual part for each parameter

## Is your feature request related to a problem? Please describe. Sometimes you're in the middle of writing a mildly-long expression using a certain function, when you forget the exact signature or behavior of it (e.g. after writing the first argument), at which point you have two options: 1. give up and press enter (which just shows you `«lambda stuff @ /some/path»`), *then* type `:doc lib.annoying.stuff` (yes, there's TAB, but still), enter, ↑↑, and finally resume typing your expression 2. ctrl+← for each token in the expression, then `:doc `, then ↑↑ restart typing, then enter, then oh fuck i forgot the :doc then restart, then ctrl+← again, then remove, then enter, then sigh ## Describe the solution you'd like If the result of an expression is a non-fully-applied function, print the docs for it (if any) in addition to the `«lambda stuff @ /some/path»` output it already gave. ## Describe alternatives you've considered Since this is a somewhat opinionated request, one alternative would be to gate this behind some kind of option. Alternatively, although this is less discoverable and is more of a "long-term dream," improvements in the repl's interface itself, such as keyboard shortcuts or popups, could be helpful in showing docs when the user needs them most but without overloading the repl's output. The final alternative is to just... not change anything ¯\\\_(ツ)_/¯ ## Additional context With regards to adding this as an option: [there is some questions to be answered as to what's the best way to add them](https://zulip.lix.systems/#narrow/channel/14-UX/topic/repl.20config.20.28rc.20file.3F.29). In addition, i also recognize that the current way the docs work have some problems that could interfere with this scenario. The biggest one I can think of is that the output of `:doc` for partial functions can be a little confusing if you're not expecting it: although the signature in the header only contains parameters that haven't been supplied yet, the body of the documentation (which is a lot more attention-grabbing than the tiny discrete signature at the top) still has the full list of input, since to nix's eyes it's just formatted text instead of having a clear separate parameter section with an individual part for each parameter

raito added the

Area/repl

labels

2026-03-26 11:34:18 +00:00

raito commented

2026-03-26 11:36:28 +00:00

Owner

It feels like to me that it would make sense to allow a project called repl2 where we would use better technologies to build a much more convenient REPL (perhaps while leveraging the Rust FFI we have) where things like LSP-style inline documentation of things under the cursor are available.

In that regards, the question becomes: how much is it worth to spend time retrofitting these features inside the current REPL?

I do not have a strong opinion on getting documentation printed at the same time with these sorts of values but I suspect this requires a layering violation to do well.

@pennae @qyriad thoughts?

It feels like to me that it would make sense to allow a project called `repl2` where we would use better technologies to build a much more convenient REPL (perhaps while leveraging the Rust FFI we have) where things like LSP-style inline documentation of things under the cursor are available. In that regards, the question becomes: how much is it worth to spend time retrofitting these features _inside_ the current REPL? I do not have a strong opinion on getting documentation printed at the same time with these sorts of values but I suspect this requires a layering violation to do well. @pennae @qyriad thoughts?

pennae commented

2026-03-26 13:49:29 +00:00

Owner

retrofitting these functions in the repl is not the problem here, it's that our data model fundamentally does not allow the feature that's being asked in the cl we linked to exist. the feature asked for in the original post is relatively easy to add, but the ux challenges we inherit from our nearly nonexistent config system make it bullshit hard even for a new repl