Provide `:doc` information through a builtin function #999

New issue

Open

opened 2025-10-01 15:31:14 +00:00 by minijackson · 2 comments

minijackson commented

2025-10-01 15:31:14 +00:00

I'm writing a documentation system for Nix, and I'd like to be able to fetch the documentation of bindings. Currently you can start a REPL and type :doc lib.something, but there's no way to export this value through a Nix expression.

Describe the solution you'd like

Something like this?:

let
  lib = {
    /** My documentation */
    myBinding = 42;
  };
in
  builtins.unsafeGetAttrDoc "myBinding" lib
  # Returns "My documentation", unprocessed, except with indents removed

Describe alternatives you've considered

Nixdoc, or parsing Nix code myself, but these solution seems hacky since the information is known by Nix.

## Is your feature request related to a problem? Please describe. I'm writing a documentation system for Nix, and I'd like to be able to fetch the documentation of bindings. Currently you can start a REPL and type `:doc lib.something`, but there's no way to export this value through a Nix expression. ## Describe the solution you'd like Something like this?: ```nix let lib = { /** My documentation */ myBinding = 42; }; in builtins.unsafeGetAttrDoc "myBinding" lib # Returns "My documentation", unprocessed, except with indents removed ``` ## Describe alternatives you've considered [Nixdoc](https://github.com/nix-community/nixdoc), or parsing Nix code myself, but these solution seems hacky since the information is known by Nix.

pennae commented

2025-10-01 15:40:56 +00:00

Owner

we actually do not have this information. nixdoc is the only reasonable way to do this at the moment, our parser discards this information as soon as it sees it. adding support for this to the parser and exposing it in nixlang would require a bunch of experimental builtins. in the long term this is something we do want to have in some shape. attaching documentation to bindings will cause rather large runtime overhead in the current architecture, so this is going to be a long way out either way.

👍 1

pennae added the

E/hard

Area/language

labels

2025-10-01 15:41:56 +00:00

jade commented

2025-10-02 16:25:41 +00:00

Owner

it should be noted that architecturally this is likely fairly possible given that nix-doc (the predecessor of today's :doc) actually supported the exact feature you're talking about, though i wouldn't necessarily say it's as useful as you'd hope.

however, because of various reasons (terminal colour, stability guarantees, rendering format), I'm not sure if reintroducing it would actually do what you want, by itself. this could be hacked in though, it's just the current architecture of things makes it a bit of a hack. i wouldn't necessarily be opposed to it as a feature provided it's clear there are no stability guarantees.

if the desire is building documentation pages, look at nixdoc (without the dash. confusing name collision. my fault).

it should be noted that *architecturally* this is likely fairly possible given that nix-doc (the predecessor of today's :doc) actually supported the exact feature you're talking about, though i wouldn't necessarily say it's as useful as you'd hope. however, because of various reasons (terminal colour, stability guarantees, rendering format), I'm not sure if reintroducing it would actually do what you want, by itself. this could be hacked in though, it's just the current architecture of things makes it a bit of a hack. i wouldn't necessarily be opposed to it as a feature provided it's clear there are no stability guarantees. if the desire is building documentation pages, look at nixdoc (without the dash. confusing name collision. my fault).