Automatically document builtin constants

[Ericson2314]

This is done in roughly the same way builtin functions are documented.

Also auto-link experimental features for primops, subsuming PR #8371.

Motivation

Keeping the documention with the code like this makes it much easier to ensure it stays up to date and in sync.

Context

Recent doc PRs alerted me to the fact that we didn't yet have this infrastructure.

I moved in the existing docs, and then wrote some rough placeholder sentences for the others.

Checklist for maintainers

Maintainers: tick if completed or explain if not relevant

• agreed on idea
• agreed on implementation strategy
• tests, as appropriate
  • functional tests - tests/**.sh
  • unit tests - src/*/tests
  • integration tests - tests/nixos/*
• documentation in the manual
• documentation in the internal API docs
• code and comments are self-explanatory
• commit message explains why the change was made
• new feature or incompatible change: updated release notes

Priorities

Add 👍 to pull requests you find important.

[fricklerhandwerk]

While I certainly agree we should have this systematically and automatically documented, I'm not sure if we should actually expose null, true, false and the hidden constants.

In general, maybe it's better to leave things undocumented rather than having a non-informative one-liner until we have something sensible. If we wait until we collect information on all of them, the PR will become really large and possibly run into merge conflicts.

[Ericson2314]

@fricklerhandwerk you can replace the strings will nullptr if you don't like them, and they won't be rendered. It is up to you.

---

I personally like the fact that even null, true, and false are important distinct values, they don't have special *syntax`: those are plain old identifiers that are used in the same way as other plain old identifiers.

[roberth]

Exposing __-prefixed constants is also not great. I think the recommendation is to

1. Use Nixpkgs lib
2. Use builtins. You can polyfill when builtins?foo == false. foo = builtins.foo or (fooReimpl)
3. Nothing. I don't think __foo should be used.

[fricklerhandwerk]

Triaged in Nix team meeting 2023-05-19:

• @fricklerhandwerk: in favor of the infrastructure support
  • should not actually add any new documentation here, would blow up scope
• @Ericson2314: just having something in the table of contents is better than nothing, even if the actual documentation contents are useless
• @fricklerhandwerk: should merge it without documentation for now
• assigned to @edolstra for review

[nixos-discourse]

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2023-05-19-nix-team-meeting-minutes-56/28446/1

[nixos-discourse]

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2023-06-05-nix-team-meeting-minutes-60/28933/1

[fricklerhandwerk]

Sorry for stalling this. This PR is a huge improvement.

[roberth]

🚀

[nixos-discourse]

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/tweag-nix-dev-update-50/29793/1