the repl's `:doc` should print documentation for built-in constants #356

New issue

Open

opened 2024-05-28 00:28:57 +00:00 by stuebinm · 2 comments

stuebinm commented

2024-05-28 00:28:57 +00:00

Member

Many of the constants defined using addConstant in src/libexpr/eval.cc actually do have a documentation string, but they are only used for generating the manual. It'd be nice if they could also be printed via the repl's :doc command (especially since the current output for things like :doc __nixPath in the repl is error: value '__nixPath' does not have documentation, which is misleading, since it is actually documented in the manual)

Describe the solution you'd like

❯ nix repl
Lix 2.90.0
Type :? for help.
nix-repl> :doc null
Synopsis: builtins.null 

    Primitive value.

    The name null is not special, and can be shadowed:

      | nix-repl> let null = 1; in null
      | 1

Implementing this seems a bit annoying, as currently the only place these documentation strings are stored is in the evaluators constantInfos, in which they are sorted by name of the constant. So afaict there's no easy way to check if a given value represents an instance of a built-in constant, thus there's also no way to get the appropriate documentation.

Maybe it would be possible to annotate values with documentation?

Describe alternatives you've considered

As a simpler alternative, the :doc command could just look constants up by name if it finds nothing else. Of course, this would then still fail to display documentation if the constant was bound to another name, and is also susceptible to printing wrong documentation if a built-in constant was shadowed.

(i have a rough patch implementing this that I'd need to clean up first, but am not at all sure if this is something anyone'd want)

## Is your feature request related to a problem? Please describe. Many of the constants defined using `addConstant` in `src/libexpr/eval.cc` actually do have a documentation string, but they are only used for generating the manual. It'd be nice if they could also be printed via the repl's `:doc` command (especially since the current output for things like `:doc __nixPath` in the repl is `error: value '__nixPath' does not have documentation`, which is misleading, since it is actually documented in the manual) ## Describe the solution you'd like ~~~ ❯ nix repl Lix 2.90.0 Type :? for help. nix-repl> :doc null Synopsis: builtins.null Primitive value. The name null is not special, and can be shadowed: | nix-repl> let null = 1; in null | 1 ~~~ Implementing this seems a bit annoying, as currently the only place these documentation strings are stored is in the evaluators `constantInfos`, in which they are sorted by name of the constant. So afaict there's no easy way to check if a given value represents an instance of a built-in constant, thus there's also no way to get the appropriate documentation. Maybe it would be possible to annotate values with documentation? ## Describe alternatives you've considered As a simpler alternative, the `:doc` command could just look constants up by name if it finds nothing else. Of course, this would then still fail to display documentation if the constant was bound to another name, and is also susceptible to printing *wrong* documentation if a built-in constant was shadowed. (i have a rough patch implementing this that I'd need to clean up first, but am not at all sure if this is something anyone'd want)

stuebinm added the

docs

label 2024-05-28 00:29:08 +00:00

jade commented

2024-05-28 02:35:38 +00:00

Owner

We would really like to be able to do this, but indeed, implementing it is a little tricky.

We *would* really like to be able to do this, but indeed, implementing it is a little tricky.

roberth commented

2024-05-29 21:40:48 +00:00

I feel like it'd be ok to "cheat" a bit and report about expressions first, and evaluated values second. That's warranted if you consider that evaluation is a lossy process (the right kind of loss, but lossy still).
Concretely, you could pattern match on expressions such as bare references and builtins.<x> and then show documentation for x.

I feel like it'd be ok to "cheat" a bit and report about _expressions_ first, and evaluated values second. That's warranted if you consider that evaluation is a lossy process (the right kind of loss, but lossy still). Concretely, you could pattern match on expressions such as bare references and `builtins.<x>` and then show documentation for x.

👍 1