C API: document whether values can be thunks

[Radvendii]

Is your feature request related to a problem? Please describe.

Right now, the documentation for nix_value_force() says

...all functions that return a value call it for you. The only place you will see a NIX_TYPE_THUNK is in the arguments that are passed to a PrimOp function you supplied to nix_alloc_primop

According to @roberth, this is not actually true (anymore?). Having an exhaustive list of places that you can see a NIX_TYPE_THUNK documented in one place is useful, but likely to get out of sync.

Describe the solution you'd like

We should instead document on each function that returns a value whether that value can be a thunk.

Describe alternatives you've considered

• Keep the list on nix_value_force() up to date (error-prone)
• Generate that list programmatically (seems complicated)
• Enforce the documentation as it currently stands is accurate. That every function that returns a value forces it (maybe not desireable?)

Priorities

Add 👍 to issues you find important.

[nixos-discourse]

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

https://discourse.nixos.org/t/2024-05-15-nix-team-meeting-minutes-146/45491/1