clarify note on forcing thunks in the C API

[fricklerhandwerk]

@prednaz follow-up on #10842 (comment)

Priorities and Process

Add 👍 to pull requests you find important.

The Nix maintainer team uses a GitHub project board to schedule and track reviews.

[roberth]

Unfortunately, this isn't correct, and it's not really actionable before other changes. (#10499)

[roberth]

This was a mistake in the design, and it already isn't true anymore that all returned Values are forced.

See #10499 for the reasons why, and #10537 for a real world counterexample.

We'll revise this doc entirely when fixing that issue.

[roberth]

Suggested change

	* @note This function is called before calling `nix_get_type()` (and therefore before most other @ref getters), because lazy evaluation should be transparent to users.
	* @note This function should be called before calling `nix_get_type()` (and therefore before most other @ref getters), because lazy evaluation should be transparent to users.

Otherwise it sounds a bit like we're describing what the bindings do. It is the reader's responsibility.

[fricklerhandwerk]

Suggested change

	* @note This function is called before calling `nix_get_type()` (and therefore before most other @ref getters), because lazy evaluation should be transparent to users.
	* @note You only need to call this function before `nix_get_type()` (and therefore before most other @ref getters), because lazy evaluation should be transparent to users of this API.

How about this then?

[roberth]

That's not necessarily true. Suppose in your application you have a hardcoded Nix function, defined in a string literal, so you know how it behaves. For example:

# passed to nix_expr_eval_from_string

{ foo, bar }:
let
  # fancy application-specific computations are declared here
in
{
  inherit baz;
  n = builtins.length qux;
}

In such a case it's valid to

1. call the function
2. retrieve the n Value
3. nix_value_force n
4. not check the type, because we know its type statically
5. call nix_get_int

Obviously a toy example, but this is a useful implementation pattern when you have a situation where a few things related things need to be computed by Nix and the application then reads the values it needs. Unlike individual function calls, you take advantage of shared computations this way.

[fricklerhandwerk]

Okay, maybe I'm misunderstanding something big time here. Apparently it's not required to call it beforehand, but sometimes it is? But saying "you should" is not very informative - do you have to or not, what are the considerations exactly?

[fricklerhandwerk]

Or maybe just delete the note if it's not gonna age well anyway.

[prednaz]

i thought, "you need nix_value_force before any api function if and only if that api function does not return a Value" was a beautifully simple rule. is it wrong? will #10499 make it wrong? cc @roberth