Any impetus for adding doc comments to the nix language?

Development
1

I understand according to rfc 72, that all documentation in nixpkgs is being upgrade to CommonMark. This is a fantastic step in the proper direction for simplifying documentation for the various pieces of the Nix ecosystem.

However, I think for the language itself, that inbuilt documentation comments, similar to rusts doc comments, would be extremely useful for the various utility functions scattered across nixpkgs. This is especially true since flakes stand to decentralize a lot of the ecosystem.

For example flake-utils resorts to documenting it’s utility functions in the project README. For it’s current size, this is fine, but as projects scale it quickly becomes a nuisance. I think it’d be much better to have a standard doc comment format. We could then generate all of a flakes documentation with something like nix flake doc.

Obviously, such a change would be a pretty extensive addition to the core Nix language, so I simply wanted to guage interest in the idea first. I’m not too well informed on the current efforts on documentation, so if this problem is already solved some other way, please forgive my ignorance :sweat_smile:

8 Likes
2

Any and all tooling to improve the ability of newcomers to learn Nix and nixpkgs should be a top priority, IMO. The number one comment I receive from people who have tried Nix is that it is an incredibly steep learning curve that is only slightly alleviated by our documentation efforts.

Standardized docstrings for functions and attributes could be exposed in a number of additional ways, including via the language server, which would get us much closer to the learning experience of, say, Guix with its Guile tooling.

2 Likes