Inline docstring support

[offlinehacker]

Is there any possibility that nix syntax could be extended and inline docstring support associated with functions would be added like in python? This would be really useful for documentation generation.

[qknight]

i would like to implement this if someone can sponsor the effort!

would be a great to have autogenerated documentation in assistant, see:
http://blog.lastlog.de/posts/nix-assistant/

(if interested, just contact me via email: [email protected])

[greedy]

I've been thinking about this as well, but was thinking more about doccomments.

I've also been thinking about the possibility of using functors for documented functions so that the documentation is actually part of the value. This makes it easier to deal with the fact that the attribute path used to access a function can't be easily determined. The documentation tool could evaluate stdenv (or any other set) and directly get the documentation for all of its function attributes. Non-function values would have to work some other way though, hmm.

[stale]

I marked this as stale due to inactivity. → More info

[Ericson2314]

I thought https://github.com/tweag/nickel had something along the lines of docstrings.

[stale]

I marked this as stale due to inactivity. → More info

[thiagokokada]

I think this is still important. Having access to :doc builtins.filter inside the nix repl already helps, but I would like this to be extended to any function.

[edolstra]

@thiagokokada See #5527 for a possible way to do this.

[thiagokokada]

@thiagokokada See #5527 for a possible way to do this.

Nice. Hope that we can eventually adopt this on nixpkgs.

[mightyiam]

I, @101v and @a-kenji are currently working on a design for in-code documentation of Nix values.

This issue seems to be the correct place for providing updates on that work. So, subscribe to this one, if you're curious or are willing to provide feedback and/or answer our occasional question.

Also, we seek funding for this activity. I've contacted NLnet to that end and haven't heard back yet.

[piegamesde]

Where does the discussion take place? Can everybody who is interested participate?

(Also, depending on the size of the feature prepare yourselves for going through the RFC process)

[mightyiam]

Where does the discussion take place? Can everybody who is interested participate?

We work in mob programming format on a regular schedule. Is this something you'd like to try participating in?

[piegamesde]

No, I'm only available for async discussion.

[blaggacao]

@mightyiam already got an idea about schema? Making unit tests part of the doc (based on examples)? Some ideas can also be observed in styx.

[mightyiam]

We started by seeing whether we can adopt the rustdoc design. It is markdown. Code examples end up as tests.

[blaggacao]

I should have linked to an example, here it goes: https://github.com/styx-static/styx/blob/master/src/lib/utils.nix#L23

We started by seeing whether we can adopt the rustdoc design.

In an attempt to explore forward-compat, you may have a look at Nickel, as well. In case you haven't yet.

[hugosenari]

Related RFC 0145 Doc-comments, not the solution, but have some use case overlap.